Dicey Table
Docs
Search the docs

Reference

AI agent error codes

What every DiceyTable AI agent error code means and how to fix it, from wrong-surface and scope-denied to token-expired and the screenshot codes.

1 min readVerified

View as Markdown
On this page6 sections

When an agent call fails, it returns isError with a short, stable code and a message that says what to do next. Find your code below. Most of the time your agent reads the code and fixes the problem by itself. This page is for the times it can't.

The codes are grouped by where they come from. If you don't know where yours came from, use your browser's find (Ctrl+F, or Cmd+F on a Mac). If the problem is that nothing connects at all, start with fix AI agent problems instead.

Codes from a tool call#

The tab answers with these when a tool can't run.

Code What it means Fix it
wrong-surface The tool doesn't run on this kind of tab, such as an editor tool on a table tab. Pass the right tab, or call page_info to see where you are.
tool-unavailable Your bridge lists a tool this site doesn't have yet. The message names the site version it needs. Wait for the site update, or use a tool the site has.
ambiguous-tab More than one paired tab could take the call. The error lists them. Pass tab: "<id>", or call session_select_tab once. See use one agent across several tabs.
no-tab No session yet, or no paired tab offers this tool. Call session_connect and pair a tab.
not-attached The tab you named isn't paired with this agent, or it closed. Call session_list_tabs and pick a paired tab.
role-denied Your role at the table doesn't allow this, or the agent tried a view it may not have. Do it from a seat or role that allows it.
read-only-lease Another tab holds this project's editor, so this tab is read-only, for you and the agent alike. Close the other tab, or ask for control in this one.
confirm-required A destructive (D) tool ran without confirm: true. The agent asks you, then tries again with confirm: true.
human-denied You clicked Deny on a confirmation. Nothing to fix. The agent should not retry without asking.
human-timeout Nobody answered a confirmation within 120 seconds. Ask the agent to try again while you are at the tab.
paused You paused the agent from the indicator. Click Resume on the indicator.
rate-limited The agent is calling faster than the tab allows. The error says how long to wait. Slow down. Limits and quotas lists every rate.
invalid-arguments The arguments don't match the tool's schema. Fix the arguments the message names.
not-found The entity, field, file, project or tool doesn't exist. Check the id, for example with scene_tree or fields_list.
not-mounted The field's panel is closed. Retry with autoOpen: true, or open the panel with panel_open.
disabled The control is turned off right now, just as a person would see it greyed out. Change whatever turns it off first.
out-of-range A value is outside the allowed range. Values are never quietly changed to fit. Use a value inside the range the message gives.
invalid The tab refused the value or file. The message gives the reason, such as a blocked file type. Fix what the message names.
focused-by-user You were typing in that field. Your typing wins. Let the agent try again after you finish.
busy The tab is already doing a job of this kind. Try again in a moment.
timeout The job took too long. Try again, or ask for a smaller job.
too-large The result or file is too big, such as a reply over the relay's 2 MB cap. Ask for a smaller size, or lower maxBytes.
internal Something unexpected broke in the tab. Run diagnostics_get and report what it shows.

Why did my key stop working?#

These come from DiceyTable's server or the bridge. Most are about your access key or your pairing.

Code What it means Fix it
no-token The bridge found no key. Run login, or set DICEYTABLE_TOKEN, then restart your MCP client.
invalid-token The key is mistyped, cut short, or unknown. Paste it again in full. If it is lost, create a new one.
token-expired The key reached its expiry date. Create a new key and run login again.
token-revoked The key was revoked. Revoked keys never come back. Create a new key.
scope-denied The key lacks the permission this tool needs, such as publish:request, or files:local for saveTo. The error names it. Create a key with that permission.
agent-access-disabled AI agent access is turned off in Settings ▸ AI agents, or the tab isn't signed in. Turn on the switch in Settings, and sign in.
too-many-tokens You already have 10 active keys. Revoke one before you create another.
too-many-sessions You already have 5 agent sessions connected. Disconnect one first.
unauthorized You aren't signed in, or a key was used where only your own sign-in works. Sign in to DiceyTable in that tab.
ticket-expired The pairing ticket ran out. Tickets last 5 minutes, and the bridge renews them while it runs. Ask the agent to reconnect. Also check your computer's clock.
ticket-invalid The pairing ticket is damaged or belongs to a different session. Ask the agent to reconnect.
ticket-user-mismatch The tab is signed in to a different account from the key. Sign the tab in to the key's account. status shows which account that is.
consent-required Nobody has approved this session yet. Type the pairing code the agent shows you.
session-ended The agent session is over. Ask the agent to call session_connect again.
invalid-request The bridge sent a request the server couldn't read. Update the bridge, then try again.
source-mismatch Only bridge sessions can use the relay. Report it. You shouldn't see this one.

A key is read when the bridge starts. After login, or after you change DICEYTABLE_TOKEN, restart your MCP client. Create an API key for your AI agent covers keys and their permissions.

Screenshot codes#

Code What it means Fix it
role-denied In a live room you host, the agent may only capture your own view (camera: "current"). In a preview, an agent camera may not look up from under the table. Use your own view. See hidden cards and AI agents.
ultra-needs-confirmation tier: "ultra" in a live room needs your confirmation first. Allow it when the tab asks.
immersive-session-active You are in VR. Leave VR, then try again.
over-budget Even the smallest image wouldn't fit maxBytes. Raise maxBytes, or ask for a smaller size.
surface-unavailable The tab is in the background (it draws nothing), the graphics device was lost, or the surface isn't open. Bring the tab to the front.
exact-capture-disabled You didn't tick Allow exact panel capture when you paired. Use the default mode: "approximate", or pair again with it ticked.
exact-capture-unsupported Exact capture needs desktop Chrome or Edge, and a panel that is on screen. Use mode: "approximate", or pass fallback: true.
needs-user-gesture Nobody clicked Allow tab capture within 60 seconds, or you declined. Click Allow tab capture on the indicator, then pick This tab.
not-self-capture You shared a different tab, a window or a screen. Nothing was captured. Next time pick This tab.

Exact panel capture for AI agents explains the last four in full.

Import and publish codes#

Code What it means Fix it
asset-too-large-after-import After conversion, the stored file is over 50 MB (64 MB for an .onnx model). Shrink or compress the file first. The message gives advice for its type.
too-large-for-type The file is over its type's own cap, such as 10 MB for an .hdr sky. Use a smaller file.
asset-exceeds-publish-limit A warning, not an error. The file was saved, but at over 45 MB it can't be published from the app. Shrink it before you publish.
ai-credits-unreviewed Publishing stopped because a person hasn't reviewed the credits an agent filled in. Review them in Mod ▸ Mod Details… ▸ Credits. See review credits an AI agent added.

A URL import also records an outcome, such as blocked-type or upstream-blocked, in Settings ▸ AI agents ▸ URL imports. How URL imports are fetched safely lists every outcome.

Messages with no code#

  • Pairing dialog text, such as "That code did not match": see fix pairing code problems.
  • "Your DiceyTable bridge is too old" (or too new): see fix an agent that won't connect.
  • agent-resume-refused in diagnostics: a reloaded tab couldn't rejoin its session and needed a new code. The pairing code page explains why.

Did this page answer your question?