> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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 <a href="#tessl-doctor" id="tessl-doctor"></a>

```
tessl doctor [--json]
```

**Flags**

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

<figure><img src="/gitbook-assets/image (84).png" alt=""><figcaption></figcaption></figure>

#### **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](/automations/troubleshooting-factory-runs.md). `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](/administrators/roles.md))
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](/projects/repairing-projects.md#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](/support/faqs.md) for common questions
- [Give feedback](/support/giving-feedback.md) or report issues to the Tessl team