Troubleshooting

401 INVALID_API_KEY

• Confirm Authorization: Bearer <key> — no typos or extra quotes
• Verify the key is active and not revoked in the console
• Ensure the key is assigned a published route

503 NO_HEALTHY_PROVIDER

• The assigned route has no eligible model for the requested capability or response_profile
• Open AI Router or Routes to verify provider connections and model coverage
• Try a simpler request (plain chat without tools) to isolate capability mismatch
• Remember that vision, tools, audio, and video each require their own model capability on the route — see the capability matrix in Models & providers

INSUFFICIENT_CREDITS or free managed limit reached

• Add credits or switch the route to BYOK
• Free workspaces may have managed onboarding caps for chat, image, and embeddings

Stream ends with event: error

• Parse the SSE error payload — see Error handling
• Check credits, route eligibility, and guardrail settings

SDK rejects model or provider fields

Expected behavior. Remove model, provider, route, and policy from SDK calls.

CLI says Not authenticated

Run one of:

latentkit login

or:

export LATENTKIT_API_KEY="lk_..."

For CI and AI agents, prefer LATENTKIT_API_KEY. For humans, latentkit login opens the browser approval flow.

CLI says Missing --tenant <workspace-id>

Logs, traces, usage, costs, providers, routes, keys, and connections are workspace-scoped commands. Pass your workspace id:

latentkit logs --tenant t_123 --days 1

Use latentkit whoami --json and latentkit apps --json to inspect the account/app context.

CLI whoami shows Account : (unknown)

Your login may still be valid, but the current session does not include the account context needed by that command.

1. Update the CLI to the latest version.
2. Run latentkit logout, then latentkit login again.
3. Confirm that the expected workspace app is selected with latentkit apps.
4. If the account is still unknown, contact support and include the CLI version; do not send the local profile file or access token.

Browser build exposes or cannot read the key

• Do not use NEXT_PUBLIC_LATENTKIT_API_KEY, VITE_LATENTKIT_API_KEY, or frontend env prefixes for secrets
• Move the LatentKit call into a backend route, server action, serverless function, Laravel controller, FastAPI route, or similar server-side layer
• The browser should call your app endpoint, for example /api/chat

PHP/Laravel request fails

• Confirm LATENTKIT_API_KEY is present in the server environment; the package reads it through config/latentkit.php
• Clear and rebuild cached configuration after changing environment values: php artisan config:clear && php artisan config:cache
• Run php artisan latentkit:check to inspect the connected app, route, credits, and latest request without printing the key
• Log the normalized exception request ID when a direct SDK or Laravel AI request fails; do not log provider response bodies

Python server hangs or leaks clients

• Use with LatentKit(...) or async with AsyncLatentKit(...) so the underlying HTTP client closes cleanly
• Set a request timeout at your framework boundary if the request can be user-triggered
• Catch LatentKitAPIError and log exc.status_code, exc.code, and exc.request_id

Still stuck?

1. Capture X-LK-Request-ID from the failing response
2. Compare your payload with Chat examples
3. Test the same key from AI Router in the console