Troubleshooting
Start with the smallest complete check, then match the observed error. Do not work around an allocation or trust failure by sending plaintext to the public API host.
Run the customer-path check
npm i -g https://api.turboprivate.ai/cli.tgz turboprivate models turboprivate check --model <live-model-id>
check uses a real room and a small paid request. A catalog page loading successfully proves only that the control service is reachable.
No model is live
Symptom: the picker says every model is offline, or allocation returns 503.
Action: confirm turboprivate models. Wait for the requested model to become live or select another model deliberately. TurboPrivate does not silently substitute an offline model.
Insufficient balance
Symptom: allocation or a turn returns 402 / insufficient_balance.
Action: add prepaid credit (see Pricing & billing). A long request or large output allowance can require a larger temporary reservation than the final charge.
Authentication failed
Symptom: 401, invalid key, or a previously working machine stops opening rooms.
Action: create a new key in the console under API keys, then run turboprivate login. For CI, confirm TURBOPRIVATE_API_KEY contains the key and no surrounding quotes or newline. Revocation is immediate.
Client must create the room capability
Symptom: an old CLI fails while opening a room with the client must create the room capability.
Action: update from the canonical tarball, then retry:
npm i -g https://api.turboprivate.ai/cli.tgz turboprivate check --model <live-model-id>
The server refuses any flow that would let it create the usable capability. This is a security boundary, not an optional compatibility flag.
Metering unavailable
Symptom: a turn returns an accounting error: usage_reservation_unavailable, usage_release_unavailable, usage_settlement_unavailable or usage_recovery_unavailable.
Action: stop new work and preserve the Room handle for reconciliation and confirmed closure. A settlement error may follow partial output; do not replay that request automatically in a new Room. Closing can remain pending while usage is reconciled. Report the timestamp, model id, request id and error code—never the prompt or API key. Older deployments may report the less specific metering_unavailable.
upstream_execution_unknown means the service could not confirm the outcome of a dispatched request. It does not mean that no computation occurred. Do not replay it automatically. A temporary reservation can remain until the outcome is reconciled; it is not a final charge based on an estimated token count.
Public /v1 returns 404
Symptom: POST https://api.turboprivate.ai/v1/chat/completions returns 404.
Action: this is expected. Embed the JavaScript/Python SDK or run turboprivate connect --print and point the client at the printed 127.0.0.1 URL. The public host never accepts plaintext inference.
Loopback port is already in use
The client starts at port 8788 and walks forward to a free port. Do not hard-code 8788 when multiple sessions run; consume the URL returned by the SDK or connect --print. Set TURBOPRIVATE_PORT to choose a different starting point.
A process exited with an open room
If a process ends without calling room.close() (or stopping connect), deletion of that Room is not confirmed and idle expiry is the fallback. Close explicitly, and check the reported cleanup state, when confirmed deletion timing matters.
Support diagnostics
Include time, model id, delivery path, CLI version, HTTP status, stable error code and request/session reference. Remove prompts, answers, file contents, API keys, loopback tokens and account keys before sharing diagnostics.