Troubleshooting

Start with:

fusionkit doctor

It checks uv/uvx, agent binaries, git, Fusion config, RouteKit connectivity, and referenced live model IDs, with a fix hint for anything missing. Run routekit doctor for provider credential checks.

"preflight failed"

A required binary, config file, provider, or model is missing. The message lists each problem with an actionable hint, such as installing uvx, installing the selected agent (codex/claude/cursor-agent), running fusionkit init, or fixing a namespaced model ID.

"no --repo given and the current directory is not a git repository"

Run fusionkit from inside your project's git repo, or pass --repo <dir>.

A panel model won't start

If a RouteKit provider cannot authenticate, discover models, or route the selected model, start with fusionkit doctor for an embedded project router. For the standalone singleton, inspect the provider and live catalog:

routekit providers status <provider>
routekit models list
routekit doctor

These daemon-backed commands use ~/.config/routekit/router.yaml; they do not discover .routekit/router.yaml by working directory. Import a project policy explicitly with routekit config import --from .routekit/router.yaml when you intend to replace the singleton's canonical document. Then correct the provider entry or its registry-defined credential/base-URL environment variable. For subscription providers, inspect routekit accounts status. FusionKit does not own provider retries or credential resolution.

--observe cannot find or start Scope

Published @fusionkit/cli packages include scope/server.js; a missing-bundle error after an npm install indicates an incomplete package and should not be fixed by installing the Scope app separately. Reinstall the npm package and report the package version if the file is still absent.

In a repository checkout, install apps/scope dependencies so the development CLI can build and run the source fallback. Maintainers validating a release must build the standalone app and run node scripts/stage-scope.mjs before the strict FusionKit pack smoke. See Observability.

Cursor needs a logged-in CLI

The cursor tool spawns the bundled Cursorkit bridge, so no separate checkout is required. It only needs a logged-in cursor-agent CLI (install) on your PATH. See Cursor.

Cursor says "Access to private networks is forbidden"

Cursor's BYOK ("Override OpenAI Base URL") requests are proxied through Cursor's backend, which deliberately blocks loopback and private addresses (ssrf_blocked). A http://127.0.0.1:... base URL can never work. Use fusionkit cursor --ide, which needs no public tunnel, or arrange external network exposure outside FusionKit. See Cursor.

Cursor says the model is not available or not valid

Cursor selects the BYOK provider by a case-sensitive prefix on the model name: claude-* uses the Anthropic key, gemini-* uses the Google key, and every other name uses the OpenAI key together with the base-URL override. A name that starts with claude- (including the dashed spelling of a Claude Code model such as claude-code-claude-fable-5) never reaches a custom OpenAI endpoint when no Anthropic key is configured.

RouteKit's /v1/cursor surface namespaces every advertised id under routekit/ (for example routekit/claude-code/claude-fable-5). Paste that namespaced id as the Model name in Cursor Settings. See Cursor.

Where are the logs?

Each run writes full per-process logs to a temp directory; fusionkit prints the path (fusion: logs in ...). Failures also surface the most relevant lines inline.

Provider keys are not picked up

Export the registry-defined variable for each configured API provider before launch. RouteKit owns provider credential resolution; use routekit doctor to diagnose missing variables. FusionKit only resolves an external router's authEnv.