For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/troubleshooting.md.
Docs

    Troubleshooting

    The Tessl CLI provides diagnostic capabilities through the tessl doctor command that outputs information about the environment and the CLI itself. This information can be helpful to support and in diagnosing issues. Additionally the CLI will provide guidance on how to resolve issues that are detected. The CLI output defaults to human readable output and can be configured to output JSON for reporting automation.

    Usage 

    tessl doctor [--json]

    Flags

    • --json (boolean, optional): Output diagnostics as JSON for programmatic processing

    Examples

    # Run diagnostics with human-readable output
tessl doctor

# Output diagnostics as JSON
tessl doctor --json

    Common Issues

    Factory runs

    If you labeled or delegated an issue and no run started, or a run failed, see Troubleshoot factory runs. tessl doctor doesn't check automations; tessl doctor --automations does, and it still starts no run.

    Authentication Issues

    If you're having trouble authenticating:

    1. Run tessl doctor to check your authentication status
    2. Try logging out and back in: tessl logout then tessl login
    3. Check that your browser allows popups for the authentication flow
    4. Verify your internet connection

    Installation Issues

    If tessl init or tessl install fails:

    1. Ensure you have the required package manager installed (npm, pip, etc.)
    2. For installing skills from GitHub, tessl install <skill> -v will provide verbose messaging, showing warning details.
    3. Run tessl doctor to identify configuration issues

    MCP Server Issues

    If your agent cannot connect to the Tessl MCP server:

    1. Verify the MCP server is configured in your agent's settings
    2. Check that tessl mcp start runs without errors
    3. Restart your agent after configuring MCP
    4. Review the MCP configuration in your agent's settings file

    Workspace Access Issues

    If you cannot access a workspace or plugin:

    1. Verify you're a member: tessl workspace list-members <workspace-name>
    2. Check your role has appropriate permissions (see Roles)
    3. Ensure you're logged in: tessl whoami

    Project Issues

    If your project appears in the Tessl web app but tessl install or tessl init in a fresh clone behaves as if no project exists:

    1. A teammate likely created the project without committing tessl.json to the repository.
    2. See project visible in the web app but missing after cloning for the recovery steps.

    Skills not found after moving the project folder on Windows

    On Windows, tessl install links each skill into your agent's skills directory using a directory junction. A junction records an absolute path. If you rename or move the project folder, every link still points at the old location and the agent finds no skills.

    Run tessl install again from the new location to restore every link:

    tessl install

    Getting Help

    If you continue to experience issues:

    • Run tessl doctor --json to capture diagnostic information
    • Visit our FAQs for common questions
    • Give feedback or report issues to the Tessl team