# Troubleshooting

## Gathering diagnostics

When something isn't working, start with `kitaru info` to see your current environment at a glance:

```bash
kitaru info
```

This shows your SDK version, connection state, server URL, active stack, config file paths, and more.

For a full diagnostic dump (including all installed packages and environment type), use:

```bash
kitaru info --all
```

### Exporting diagnostics for support

If you're opening a [GitHub issue](https://github.com/zenml-io/kitaru/issues) or asking for help in the [ZenML Slack](https://zenml.io/slack), include the output of `kitaru info` so we have the full picture. The easiest way is to export it to a file:

```bash
kitaru info --all --file debug.json
# or: kitaru info --all --file debug.yaml
```

{% hint style="info" %}
Environment variables with secret-like names (containing TOKEN, KEY, SECRET, PASSWORD, CREDENTIAL, or AUTH) are automatically masked in the exported file. Review other fields such as server URL before sharing publicly.
{% endhint %}

You can also get JSON output directly for pasting into an issue:

```bash
kitaru info --all -o json
```

## Resetting Kitaru state

If your local database is in a weird state, connections are stale, or you just want a fresh start, `kitaru clean` will get you out of trouble.

### Preview before deleting

Always use `--dry-run` first to see what would be removed:

```bash
kitaru clean project --dry-run   # Preview project-local cleanup
kitaru clean global --dry-run    # Preview global config cleanup
kitaru clean all --dry-run       # Preview both
```

### Clean scopes

| Command                | What it removes                                              |
| ---------------------- | ------------------------------------------------------------ |
| `kitaru clean project` | The `.kitaru/` directory in the current project              |
| `kitaru clean global`  | The global config directory (database, stores, server state) |
| `kitaru clean all`     | Both project and global state                                |

### Safety features

* **Auto-backup:** Before removing global state, the SQLite database is backed up automatically
* **Model registry protection:** If you have registered model aliases, `clean global` and `clean all` require `--force` to confirm
* **Local server teardown:** A running local server is stopped before cleanup
* **Confirmation prompt:** You'll be asked to confirm unless you pass `--yes`

### Common scenarios

**Database in a bad state:**

```bash
kitaru clean global --force --yes
kitaru login
```

This backs up your database, removes all global state, and starts fresh.

**Starting a new project from scratch:**

```bash
kitaru clean project --yes
kitaru init
```

**Full reset (nuclear option):**

```bash
kitaru clean all --force --yes
kitaru init
kitaru login
```

## Analytics

Kitaru collects anonymous usage analytics to help improve the product. You can check your current preference and opt out at any time:

```bash
kitaru analytics status      # Show current preference
kitaru analytics opt-out     # Disable analytics
kitaru analytics opt-in      # Re-enable analytics
```

The preference is persisted to your config file, so it applies to all surfaces — CLI, SDK, and MCP servers. This is important because MCP clients launch `kitaru-mcp` in a sanitized environment where shell environment variables (like `ZENML_ANALYTICS_OPT_IN`) are not available.

{% hint style="info" %}
If you previously disabled analytics via the `ZENML_ANALYTICS_OPT_IN=false` environment variable, run `kitaru analytics opt-out` to persist the preference to your config file. The environment variable alone does not reach MCP server subprocesses.
{% endhint %}

## Getting help

* [GitHub Issues](https://github.com/zenml-io/kitaru/issues) — bug reports and feature requests
* [ZenML Slack](https://zenml.io/slack) — real-time help from the team


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zenml.io/kitaru/getting-started/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.