Troubleshooting
Start from what you see, find the likely cause, and apply the fix. Messages are quoted as they appear in Baseera.
Find the symptom, read the cause, apply the fix. Messages are quoted as they appear in the dashboard and in the SDK.
Start with the agent's Integrate page. Integration health checks your publishable key, allowed domains, provider key, published version and whether a session has reached Baseera. Most "nothing happens" problems show up there.
The assistant does not answer
The SDK received agent_not_configured. The agent has no model or no provider key. Open Assistant, choose a Provider key and a Model, save, then publish. See Instructions and model.
The model provider failed. Open Provider keys and look at the key's state: Key rejected (replace the key), Out of credit (add credit at the provider), Provider unavailable (usually clears), or Key removed (pick another key on the agent). The agent shows "This agent can't answer right now" with Open provider keys. The session trace shows the error code on the failed model call. See Provider keys.
The provider is rate limiting your key (provider_rate_limited). It usually clears by itself. If it keeps happening, ask the provider for a higher limit or use a different key.
A monthly limit is full (limit_reached). Raise it on the agent's Overview, or the tenant default in Settings. See Spending limits.
The per-user, per-tenant or per-agent rate limit was hit (rate_limited). Raise it under Rate limits on the Assistant page and publish.
The browser could not reach the runtime. Check the runtime address in your app, your network, and that your domain is allowed.
Saving goes to the draft. Your users get the production version, so publish. The status in the bar says Draft until you do. See Preview and publish.
Your app cannot connect
The domain your app runs on is not in Allowed domains on Deploy & access. Add it exactly as the browser shows it, with the port if there is one, for example localhost:3300. Use *.example.com for subdomains.
The key in your app is wrong or was revoked. Create a new publishable key (pk_) and update NEXT_PUBLIC_BASEERA_KEY or the equivalent in your app. Restart your dev server after changing environment files.
Your server must sign a user token with the agent's secret key (sk_). invalid_user_token means the token is missing or wrong. user_token_expired means it ran out, so the SDK should ask your token route for a fresh one before it expires. See User tokens.
Development mode lets localhost skip the token. In production your server must sign tokens. Integrate shows "Only anonymous sessions so far". Turn Development mode off before going live.
After three minutes it lists causes from your settings: no publishable key, domain not allowed, no provider key on the model, or nothing published. If none applies, check that the provider and surface are mounted in your app and that the key is the one shown on Integrate. See Embed.
In the quickstart, a 500 means BASEERA_SECRET_KEY is missing or is not an sk_ key, and a 403 means the request was not a same-origin POST. See the quickstart.
The component that registers tools is not mounted, or no turn has been sent. Send a message and reload Tools. See Tools.
Provider keys
The key's shape is wrong for the provider you chose, or it was cut off. Anthropic keys begin sk-ant-, OpenAI sk-, Google AIza and OpenRouter sk-or-.
The key is wrong, revoked, or lacks permission. Create a new one at the provider with model access.
Key checks are limited to 10 a minute per person and per organization. Wait the number of seconds shown.
Your organization requires two-factor. Open Security, sign in with your code, and retry. The same applies to creating keys and changing webhook secrets.
Anthropic does not offer embedding models. Add an OpenRouter, OpenAI or Google key.
Knowledge
Check, in order: the knowledge base is attached on the agent's Knowledge page and published; the source is Ready, since sources still processing are not searched; and Test retrieval returns the passage. If the user's token has no matching claim or tenant, the source is hidden. See Knowledge access.
The session trace says why: no search ran (improve the prompt, or use Search on every turn), a search found nothing relevant, or sources were found but not cited.
The knowledge base uses an English-first embedding model. Create a new knowledge base with a multilingual model.
Even OCR found no text. Upload a text version.
Split the file into smaller ones.
The parser is not available in this environment. Contact your Baseera administrator. Markdown, TXT, HTML and CSV still work.
Fix the knowledge base's embedding key in its Embedding settings (or add credit), then press Retry on each failed source.
Open the website row for the reason. Common ones: "The site's robots.txt does not allow this address to be read.", "No page could be read, so nothing was changed. Check that the site is up and public.", "More than half of the pages could not be found this time, so none were removed." See Crawl a website.
The organization is at its limit for original files. Delete sources you no longer need.
Approvals and tools
The tool was registered as read. Change its kind to write or draft. See Tools.
The tool has no describe function. Add one that returns a plain sentence.
The tool has no undo, the call failed, or the page was reloaded. Undo data lives in memory only. See Approvals.
Add a mock for that tool in the test. Tests never call your real tools.
Publishing and tests
The tooltip says why: "Only an owner or admin can deploy.", "Nothing to deploy: there are no unpublished changes." or "A required test failed. Fix the draft, then run Check all." An owner can still publish past failing tests, with a written reason.
Someone edited the draft while the dialog was open. Close it, review the draft again and publish.
Choose an active key on the Assistant page and save.
Wait for the run to finish or press Stop run, or wait until the hour passes.
That is not the assistant's fault. It is usually a missing or expired provider key. Fix the key and run again.
Webhooks
Webhooks go to public https addresses only. For local development, use a tunnel.
Check the reason in Recent deliveries: Timed out (answer within 5 seconds, 10 for knowledge events), Couldn't connect, Address not found, Redirected (not followed), or Answer N (your server did not return a 2xx). The agent's Overview shows Finish webhook problem when the latest finish delivery failed. See Webhooks.
Verify against the raw body with the current secret. Saving the webhook again rotates the secret and destroys the old one.
Team and sign-in
The link expired (7 days), was already used, was revoked, or the account you signed in with has a different email address than the invitation. Ask for a new invitation.
The session has not passed the code step. Sign out, sign in and enter your authenticator code.
At the code prompt choose I lost my authenticator and enter a recovery code. It removes your authenticator, so you can set up a new one. If you have no recovery codes, ask another owner.
Check your credentials. For a new account, open the confirmation link in your inbox. Use Forgot password? to reset.
An organization needs at least one owner. Promote another person before you leave or demote yourself.
Still stuck
Open the session in Sessions and read the trace: the error code is on the failed model call and on the turn. Include it when you contact support.