Skip to Content
Baseera Docs

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 saysCause 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 missingImmersive 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

  • useBaseeraImmersive must run inside BaseeraProvider, 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.type or entity.ref starts 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:

CodeCause
origin_not_allowedThe page's origin is not in the agent's allowed domains.
invalid_keyThe publishable key is unknown or revoked.
invalid_user_token or user_token_expiredThe token is missing, malformed or expired. The SDK retries once on expiry.
session_not_foundThe session is not this user's and this agent's.
invalid_requestAn override without a reason, a reason outside 10 to 1,000 characters, or an override that does not cover every open blocking check.
rate_limitedToo 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.

CodeCause and fix
receipt_not_foundThe receipt is unknown, malformed or another agent's. Check you send receipt from the action, and that agentId is this agent's.
entity_mismatchThe route's entity is not the record the receipt was recorded for. Use the same type and ref.
receipt_expiredOver 10 minutes old. Ask the person to finish again.
receipt_usedVerified before. A retry of the same request, or your route failed after a first success. Finish again for a new receipt.
override_requiredA 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.
unavailableNetwork 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 get returns something that cannot be serialized, a change is not noticed. Return strings, numbers and plain objects. For anything that is not a field, call recheck().
  • 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 fields and the field is wrapped in BaseeraField.
  • 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.

  1. The id is in the screen's aiChecks. A check on the agent that the screen does not list is ignored.
  2. 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.
  3. The agent has a provider key and a model. Without them you get agent_not_configured or provider_key_missing, and AI checks are skipped quietly.
  4. The record opened, or a value changed and 1.5 seconds passed. A burst of typing makes one run.
  5. 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.
  6. You are under the cap: 20 runs per record per session and one every 5 seconds. Past it, the answer has capped: true or retryAfterMs.

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 BaseeraField and keep it mounted. ui.prefillDraft and ui.focusField exist only while at least one field is on screen.
  • name on BaseeraField does not match a field declared in useBaseeraImmersive({ 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 fix with a field, or the field is not on screen. applyCheckFix resolves null.

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

  • proactive is false on BaseeraSurface.
  • 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: idleMs is 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.

ShowsDo this
No deliveriesNo record was finished since the webhook was saved, or no webhook is set ("No webhook set up yet.").
WaitingThe first try is on its way, or the retry waits for the next worker pass, about a minute.
Address not allowedUse a public https address. Private, local and internal addresses are refused at save and at every send.
Address not foundCheck the host name.
Timed out after 5 secondsAnswer within 5 seconds. Do the slow work after you answer.
Redirected (not followed)Use the final address. Redirects are not followed.
Answer 4xx or 5xxYour handler rejected it. Check the signature step below.
Gave upBoth 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 the Request itself 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 }:

CodeCause
invalid_requestThe 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_tokenThe secret key is wrong, for another agent, or a publishable key.
idempotency_conflictThe same idempotencyKey was used with different content.
rate_limitedOver 600 calls a minute per key or 1,200 per agent. Wait retryAfter.
unavailableNetwork 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.

Next steps

On this page