Troubleshooting

Diagnose problems and reset Kitaru state

Gathering diagnostics

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

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:

kitaru info --all

Exporting diagnostics for support

If you're opening a GitHub issue or asking for help in the ZenML Slack, include the output of kitaru info so we have the full picture. The easiest way is to export it to a file:

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

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.

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

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:

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:

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:

kitaru clean project --yes
kitaru init

Full reset (nuclear option):

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:

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.

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.

Getting help

• GitHub Issues — bug reports and feature requests

• ZenML Slack — real-time help from the team