Get startedHelp

Troubleshooting

Find the error you're seeing, what causes it and how to fix it, for LatentCode, LatentWork, the Agents API and the console.

Reading a gateway error

Every product sends its model requests through the gateway, so most problems show up as a gateway error. The error names the problem in its type and explains it in message. LatentCode and LatentWork show the message; the full error looks like this:

JSON

{
  "error": {
    "message": "Model 'claude-opus-5' is not allowed for your tier 'Free'",
    "type": "model_not_allowed"
  }
}

Error reference

Status	type	Meaning
401	invalid_api_key	The key is missing, wrong, or regenerated. Details
403	org_access_denied	You aren't a member of the organization the request is for. Details
403	project_access_denied	You aren't in the team, or the team belongs to another organization. Details
403	no_tier_assigned	No tier applies to you in this organization. Details
403	model_not_allowed	Your tier doesn't include the model. Details
400	guardrail_blocked, guardrail_blocked_llm, guardrail_blocked_pii	A guardrail blocked the request. Details
400	invalid_request_error	The request itself is wrong. Details
402	budget_exceeded	A tier spending budget is used up for the current window. Details
402	credit_limit_exceeded	Your organization's or your own credits have run out. Details
429	rate_limit_exceeded	Too many requests. Details
502	varies	The model provider failed or rejected LatentStack's credentials. Details

Authentication and access

401: Invalid API key

JSON

{ "error": { "message": "Invalid API key", "type": "invalid_api_key" } }

Cause. The gateway doesn't recognise the key. Usually it was regenerated (the old key stops working at once), copied with a missing character, or the account was deleted.

Fix. Copy the key again from Account settings → API Key (open it) and update every client that uses it. In LatentCode, run latentcode config set api-key ls-….

A related message with the same status and type:

message	Cause and fix
API key required. Send 'Authorization: Bearer <your-key>'.	No key was sent. Add an `Authorization: Bearer ls-…` header, or `x-api-key: ls-…`.

403: Not a member of this organization

JSON

{ "error": { "message": "You are not a member of this organization", "type": "org_access_denied" } }

Cause. The request's X-Org-Id header names an organization you don't belong to, often because you left or were removed and the client still has it selected.

Fix. Pick an organization you belong to in the client, or drop the header to use your default organization. List yours with:

$curl https://latentstack.dev/v1/orgs -H "Authorization: Bearer $LS_API_KEY"

403: Team errors

message	Cause	Fix
You are not a member of this project	The request names a team (`X-Project-Id`) you aren't in.	Choose one of your teams (see My Teams in the console), or ask an admin to add you.
This team is not available in the selected organization	The team belongs to a different organization from the one the request is for.	Switch to the team's organization, or choose a team in the current one.

403: No access tier

JSON

{
  "error": {
    "message": "No access tier is assigned for this account in the selected organization. Ask an administrator to assign one.",
    "type": "no_tier_assigned"
  }
}

Cause. No tier applies: not the team's, not yours in the organization, not the organization's default. See Which tier applies.

Fix. Ask an organization admin to assign you a tier on the Users page, or to set a default tier on the Tiers page.

403: Model not allowed

JSON

{ "error": { "message": "Model 'claude-opus-5' is not allowed for your tier 'Free'", "type": "model_not_allowed" } }

Cause. Your tier's allowed models don't include the one you asked for. Tiers can differ between organizations and teams.

Fix. Pick a model from your model list, which only shows the models you can use. In LatentCode, run latentcode config models --refresh to update the model list. To get the model added, ask an admin to add it to your tier.

Request errors

400: Blocked by a guardrail

JSON

{
  "error": {
    "message": "Your request was blocked because it contained sensitive data.",
    "type": "guardrail_blocked_pii",
    "entities": [{ "entity": "US_SSN", "count": 1 }]
  }
}

type	Default message	What happened
guardrail_blocked_pii	Your request was blocked because it contained sensitive data.	The request contained data the organization's PII guardrail blocks. `entities` lists what was found and how often.
guardrail_blocked_llm	Your request was blocked by an AI safety policy.	The AI policy check found the request breaks a policy. `policy` names it when known.
guardrail_blocked	Your request was blocked by a content guardrail.	The request matched a blocking content rule. `guardrail` names the rule.

Admins can replace the default messages, so yours may differ. Remove the flagged content and try again. If you think the block is wrong, tell an organization admin: guardrails are set per organization on the Guardrails page. When the PII guardrail is set to sanitize, it removes the data and the request goes through.

400: Invalid request

message	Fix
'messages' must be a non-empty array	Send at least one message in `messages`.
'max_tokens' must be a positive integer	Set `max_tokens` to 1 or more, or leave it out.
Model <model> does not support tools	Remove `tools`, or use a model that supports tool calling.
<model> does not support reasoning effort '<effort>' — supported: …	Use one of the listed levels.
reasoning effort '<effort>' is not available for <model> here — allowed: …	Your organization offers fewer levels than the model supports. Use one of the allowed ones.
'<model>' on '<provider>' has no price, so every call would bill at zero …	Your server has no price for this model on this provider. Tell your administrator.
Provider '<provider>' has no id declared for model '<model>', so it cannot serve it. …	This model isn't set up correctly on your server. Tell your administrator.
HTTP 400: …	The provider rejected the request. A common case is a prompt longer than the model's context window: shorten it, or start a new conversation.

Limits and spending

429: Rate limit

JSON

{
  "error": {
    "message": "Rate limit timeout: waited <N>s …",
    "type": "rate_limit_exceeded"
  }
}

Cause. Your tier limits how many requests you can make per model per minute, hour, 6 hours and day. Near a limit, requests slow down; past it, they fail with 429.

Fix. Check Rate limit usage (per model) on My Usage to see which limit you hit, slow down, or ask an admin for a higher tier. Admins can reset a user's counters.

402: Budget exceeded

JSON

{
  "error": {
    "message": "Budget exceeded for window 'day': spent $5.0132 of $5.0000",
    "type": "budget_exceeded",
    "window": "day",
    "model": null
  }
}

Cause. Your tier caps spend per window (min, hour, 6h or day), and you've reached it. When model is set, the cap is that model's daily budget.

Fix. Wait for the window in window to reset, or switch to a cheaper model if only a per-model budget is used up. Budget usage (USD) on My Usage shows where you stand. To get warned before this happens, set up Budget Alerts.

402: Credit limit exceeded

JSON

{
  "error": {
    "message": "Credit limit exceeded (member): $0.0000 of $20.0000 remaining",
    "type": "credit_limit_exceeded",
    "scope": "member",
    "remaining": 0,
    "limit": 20
  }
}

Cause. Credits don't reset on their own. scope says whose ran out: member is your own allowance within the organization, org is the whole organization's pool.

Fix. For member, select Request Credits on My Usage; an admin approves it on Credit Requests. For org, an organization admin needs to top up the pool.

502: Provider errors

A 502 means the model provider couldn't complete the request. The message starts with the provider's status, for example HTTP 503: ….

What you see	Cause	Fix
HTTP 5xx: …	The provider had an outage or was overloaded. The gateway already retried.	Try again shortly, or use another model.
HTTP 401: … or HTTP 403: …	The provider rejected the credentials LatentStack uses for it. Your key is fine.	Tell your administrator. Provider credentials are set in the console.
provider '<name>' has no … — set one on the Providers page	The provider serving this model isn't set up on your server.	Tell your administrator.
Other messages	A timeout or network problem between the gateway and the provider.	Try again. If it keeps happening, tell your administrator.

LatentCode

Invalid API key when setting the key or connecting

Cause. The gateway rejected the key (HTTP 401 or 403).

Fix. Copy the key again from Account settings and run latentcode config set api-key ls-…. Check the gateway URL with latentcode config.

Could not reach gateway (… → HTTP 404) or Could not reach …

Cause. The gateway URL is wrong or unreachable. It must be your server's address followed by /v1. latentcode config set base-url warns when the URL doesn't end in /v1.

Fix. Run latentcode config set base-url https://latentstack.dev/v1, then latentcode config models --refresh. If it still fails, check that https://latentstack.dev opens in a browser on this machine.

No models returned for this key (empty tier?)

Cause. The key works, but no models are available to you: your tier allows none, or no tier applies.

Fix. Ask an organization admin to assign you a tier with at least one model.

The Connect LatentRouter dialog keeps coming back

Cause. LatentCode won't start a session until the gateway accepts your key, so the first-run dialog reopens until a key validates.

Fix. Enter a working key, or press ctrl+c to quit and set it with latentcode config set api-key. Press esc on the key step to go back and correct the gateway URL.

A model I expect is missing from the model list

Cause. LatentCode lists the models it imported the last time the key was checked. Tier changes don't show until it imports again.

Fix. Run latentcode config models --refresh. If the model is still missing, it isn't in your tier for the selected organization or team.

Collecting details for a bug report

Run the failing command with logs printed to the terminal:

$latentcode run "hello" --print-logs --log-level DEBUG

Include the output of latentcode --version and latentcode config. The config output masks your key, but check what you share.

LatentWork

The profile menu says Gateway unreachable

Cause. Your API key is wrong or was regenerated.

Fix. Copy your current key from Account settings, paste it into Settings → LatentRouter and save.

Server unreachable. Check the URL and try again.

Cause. LatentWork couldn't connect to the URL within the time limit.

Fix. Check the URL is your server's address, for example https://latentstack.dev, and that this machine can open it in a browser.

Server returned an error (…)

Cause. The server answered, but not successfully.

Fix. Check the URL points at your LatentStack server and not at another site on the same host.

Console

An account with this email already exists

Sign in instead. If you don't know the password, choose the forgotten-password link on the sign-in page to get a reset code by email.

Too many sign-up attempts from this network. Please try again later.

Too many sign-ups came from your network. Wait a few minutes and try again.

My invitation link doesn't work

Invite not found or already used: the link was used, revoked or replaced by a newer invitation. Ask for a new one.
This invite has expired: invitations last 14 days. Ask for a new one.
This invite was sent to …: you're signed in with a different email address. Sign out and sign in (or sign up) with the invited address.

I can't see the Administration pages

They're for organization owners and admins, in the organization that's active. Check the organization switcher, then ask an owner to make you an admin if you need access.

My usage is in the wrong organization

Usage is counted against the organization each request was for. Clients use your default organization unless you pick another one in the client. See Organizations.

Installing

Problems with the installer, PATH, missing builds or blocked executables are covered in Install → Troubleshooting.