Troubleshooting
Symptom first: the Finish button stays disabled, a check never runs, a draft does not show, the server refuses a finish, a webhook is not delivered, and more.
Find what you see, then follow the causes in order. Error codes are the ones Baseera returns. See Errors for the full list.
The Finish button stays disabled
Read the line under the button first. The default bar says why.
| The line says | Cause and fix |
|---|---|
| "N issues block Send invoice" | A blocking check is open. Fix it, or use Finish anyway with a reason. |
| "N warnings block Send invoice" | You set blockOnWarnings. Fix the warning or press Got it. |
| "Checks couldn't run; finish is disabled." | A blocking check threw an error. Fix its run function. The override is unavailable until it runs. |
| "This record is closed" | finish.closed is true. This is on purpose: there is no button. |
| No line, and the button is missing | Immersive mode is not active. See below. |
If an issue is open and you cannot see why, check for an AI check. One with Can block finish on holds the finish while its latest result fails, and it counts in openBlocking.
Immersive mode is not active
useBaseeraImmersivemust run insideBaseeraProvider, in a component that is mounted.- A second call replaces the first. Only one record is in immersive mode at a time. In development the console names both records.
- Changing
entity.typeorentity.refstarts a new record and re-runs the checks. - Without a user token (outside dev mode) the session cannot start and fails with
invalid_user_token.
Finish is enabled but pressing it does nothing
finish() records the finish with Baseera first. If that fails, your action never runs and the bar shows "Couldn't record the finish, so nothing was sent. Try again." (finishError is record_failed). Look at the network tab for the finish request:
| Code | Cause |
|---|---|
origin_not_allowed | The page's origin is not in the agent's allowed domains. |
invalid_key | The publishable key is unknown or revoked. |
invalid_user_token or user_token_expired | The token is missing, malformed or expired. The SDK retries once on expiry. |
session_not_found | The session is not this user's and this agent's. |
invalid_request | An override without a reason, a reason outside 10 to 1,000 characters, or an override that does not cover every open blocking check. |
rate_limited | Too many requests. Wait the retryAfter seconds. |
If the bar shows "The finish didn't go through. Try again." the receipt was recorded but your action threw (action_failed). The person finishes again to get a new receipt.
If the reason box says "Write a reason of 10 to 1000 characters.", the override reason is too short or too long after trimming.
My server refuses the finish
verifyFinish returns a code. It never throws.
| Code | Cause and fix |
|---|---|
receipt_not_found | The receipt is unknown, malformed or another agent's. Check you send receipt from the action, and that agentId is this agent's. |
entity_mismatch | The route's entity is not the record the receipt was recorded for. Use the same type and ref. |
receipt_expired | Over 10 minutes old. Ask the person to finish again. |
receipt_used | Verified before. A retry of the same request, or your route failed after a first success. Finish again for a new receipt. |
override_required | A blocking check was open, and the person's override does not cover it. Your server's openBlocking list is stricter than the browser's: either fix the record or let the person override with a reason. |
unavailable | Network error, timeout (5 seconds), a redirect, a non-200 answer, a bad secret key, or a baseUrl that is not HTTPS. Check BASEERA_RUNTIME_URL and the key, then retry. Treat it as a refusal. |
Also check that the secret key is the agent's own and not a publishable key. On the server endpoints a wrong key is invalid_server_token.
A check never runs, or never changes
- Your own check. Checks run when immersive mode starts and 250 ms after a field value changes. The value is compared as JSON: if
getreturns something that cannot be serialized, a change is not noticed. Return strings, numbers and plain objects. For anything that is not a field, callrecheck(). - A check that throws. It counts as failed with "This check could not run." In development the console says which check.
- The check names the wrong field. A flag shows on a field only if the check lists the field's name in
fieldsand the field is wrapped inBaseeraField. - A client signal. It is ignored when the name is outside
^[a-z0-9_.-]{1,64}$, the data is over 2 KB, or no record is open. Development logs a warning.
An AI check never runs
Work through these in order.
- The id is in the screen's
aiChecks. A check on the agent that the screen does not list is ignored. - The check is published. AI checks are saved to the agent's draft and go live when you publish on Deploy. The runtime reads the latest published version.
- The agent has a provider key and a model. Without them you get
agent_not_configuredorprovider_key_missing, and AI checks are skipped quietly. - The record opened, or a value changed and 1.5 seconds passed. A burst of typing makes one run.
- Values did not change since the last run. A result is cached per session, record, check, agent version and a hash of the values, and returned without a model call until something changes.
- You are under the cap: 20 runs per record per session and one every 5 seconds. Past it, the answer has
capped: trueorretryAfterMs.
If a run happened and there is still no result, the model's answer for that check was dropped as invalid (ai_check_invalid in the trace): a repeated or unknown id, an empty or too long message, an undeclared field, or a source the run did not find. A dropped check has no result. It is not the same as passing.
On the dashboard, Needs attention lists AI checks that have never run.
A draft does not show
A draft is shown under the field. If it does not appear:
- The field is not on screen. Wrap the input in
BaseeraFieldand keep it mounted.ui.prefillDraftandui.focusFieldexist only while at least one field is on screen. nameonBaseeraFielddoes not match a field declared inuseBaseeraImmersive({ fields }).- The value is not JSON, or over 2 KB. The model gets an error result.
- A newer draft replaced it. The older one is rejected with "replaced by a newer draft".
- The record closed, or the turn was stopped. Pending drafts are rejected.
- A check's Apply fix does nothing when the check has no
fixwith afield, or the field is not on screen.applyCheckFixresolvesnull.
If Approve does not change the input, your onChange on BaseeraField does not write to your state. Baseera writes only through it.
The assistant never speaks up
proactiveis false onBaseeraSurface.- The only open issues are info. Only blocking and warning open a notice.
- The person pressed Later on it. It still counts in the badge.
- The person is not idle:
idleMsis 1,500 by default, and a focused field or an open mobile keyboard counts as active. - The model raising a check on its own (
immersive.notice) is not available yet.
The webhook is not delivered
Open the agent's Immersive mode page and read Recent deliveries.
| Shows | Do this |
|---|---|
| No deliveries | No record was finished since the webhook was saved, or no webhook is set ("No webhook set up yet."). |
| Waiting | The first try is on its way, or the retry waits for the next worker pass, about a minute. |
| Address not allowed | Use a public https address. Private, local and internal addresses are refused at save and at every send. |
| Address not found | Check the host name. |
| Timed out after 5 seconds | Answer within 5 seconds. Do the slow work after you answer. |
| Redirected (not followed) | Use the final address. Redirects are not followed. |
| Answer 4xx or 5xx | Your handler rejected it. Check the signature step below. |
| Gave up | Both tries failed. Fix the cause. Finishing records was not affected. |
If your handler rejects with 400, the signature check failed:
- Pass the exact raw body to
verifyWebhook, before any JSON parsing. Or pass theRequestitself in a Fetch-style handler. - Use this endpoint's secret. Saving the webhook again rotates the secret and destroys the old one.
- Your server clock must be within 5 minutes of real time. The default tolerance is 300 seconds.
The payload is up to about 250 KB. If your framework limits the body size, raise it. Ignore event types you do not know: the same address receives eval.run.finished.
A server signal fails
baseera.signal returns { ok: false, code }:
| Code | Cause |
|---|---|
invalid_request | The name or data breaks the rules: a name over 64 characters or with other characters, nested data, over 20 keys, a long value, or a key or value that looks like a secret. |
invalid_server_token | The secret key is wrong, for another agent, or a publishable key. |
idempotency_conflict | The same idempotencyKey was used with different content. |
rate_limited | Over 600 calls a minute per key or 1,200 per agent. Wait retryAfter. |
unavailable | Network error or a 5xx after one retry. Try again. |
A server signal makes AI checks stale. It does not re-run them on a screen that is open: they run the next time the record is opened.
The trail has gaps
The trail is best effort. A failing batch is retried twice and then dropped, and a closed tab sends one last keepalive request. When the agent does not store tool data, draft values, previous values and signal data are removed on purpose. In the webhook, truncated: true means the oldest events were left out.