Troubleshooting, every error in plain words
Studio's errors have one shape: a code, a status and a message in words, plus details. A coding agent sees them as code (status): message (details). Look the code up here.
Connection and permissions
| Code | Means | Do |
|---|---|---|
unauthenticated (401) | No sign-in or token, or it expired. | Sign in again, or reconnect the MCP client. |
forbidden (403) | Your account may not do this. | Ask your workspace admin for the permission the action needs. |
insufficient_scope (403) | Your token or sign-in lacks a scope (the details name it, for example functions:write). | Reconnect with an API token, or wait for the OAuth function scopes to land. |
scope_missing (403, landing) | You called a tool by name that your connection cannot see. | Same as above. |
feature_disabled | This feature is switched off on this deployment (the message names it). | Ask Bicycle. |
not_found (404) | The object does not exist, or belongs to another workspace, or you cannot see it. | Check the id and the workspace you signed in to. |
viewer_required | The action needs a signed-in person, not a service identity. | Do it from Studio's pages. |
auth_service_unavailable (503) | Bicycle's sign-in service could not be reached. | Retry in a minute; tell Bicycle if it persists. |
rate_limited (429), concurrency_limited | Too many calls at once. | Wait and retry; the details give a retry hint. |
quota_exhausted | A daily budget is used up (agents, analyses, evaluations). | Wait for the reset, or ask an admin. |
timeout, deadline_exceeded, host_timeout, unreachable | Something took too long or could not be reached. | Retry; if it persists, check the run's trace and tell Bicycle. |
Data apps
| Code | Means | Do |
|---|---|---|
query_not_allowed | The app asked for a query its manifest does not declare. | Declare it under queries and upload a new version. |
query_unknown | A query id the app does not declare. | Same. |
query_param_missing, query_param_undeclared | A query was called without a declared parameter, or with one it does not declare. | Match the call to the manifest's parameters. |
store_not_declared | A cache key or blob the manifest does not declare. | Declare it under cache or blobs. |
fn_not_declared | Code named a function or workflow the manifest does not import. | Add it under functions, pinned, and upload a new version. |
input_invalid | The input does not match the function's input schema. | Fix the input; the details say which field. |
input_too_large | Over 64 KB of JSON. | Put large inputs in a blob. |
version_conflict (409) | Someone created a version after the one you expected. | Re-read the app's versions and try again. |
package_invalid, bundle_file_missing, package_digest_mismatch | The uploaded zip is not right: a file missing, a wrong name, or the bytes differ from what you said. | Rebuild (npm run build), zip bda.manifest.json, app.js, app.css at the root, upload again with the right size and sha256. |
a version is invalid with per-query errors | A declared query does not compile against the model. | Run it with query_run first; fix the SQL; upload a new version. |
function_not_shared | The app imports a function that is not shared with the workspace or not exposed to apps. | Ask the function's owner to share and expose it. |
name_invalid | A name breaks the rules (lowercase, digits, underscores). | Rename. |
snapshot_app_not_shared | A workflow or schedule wants a picture of an app that is not shared with the whole workspace. | Share the app with the workspace, or drop the screenshot step. |
recipient_not_allowed | On preview, an email address outside the allowlist. | Use an allowed address. |
Functions
| Code | Means | Do |
|---|---|---|
"A person must confirm this in Studio before vhuman_publish_required) | A first or widening publish. Not an error. | Open the link, read the summary, press Publish. |
human_policy_required | A policy says a person must decide. | Do it in Studio. |
draft_conflict (409) | Someone else saved the draft first (the details say who and when). | Re-read the draft, re-apply your change, tell the other person. |
version_not_listed | A tool called a function version without a fresh tool list. | List tools again, then call. |
function_disabled (409) | The function is disabled. | Ask the owner to enable it, or use another; do not re-create it. |
function_not_found (404) | Unknown or unpublished reference, or not exposed to this surface. | Check the reference and the function's exposure. |
function_withdrawn | The version was withdrawn. | Pin a current version. |
capability_not_granted | The code used a capability its manifest does not list (or the calling app or workflow did not declare the query id). | Add the capability, or declare the query in the caller; publish. |
capability_unsupported, kind_unsupported | This deployment does not run that capability or kind. | Ask Bicycle. |
kind_requires_async (422) | You called a slow kind (agent, workflow) synchronously. | Use :submit and poll, or { wait: false } from an app. |
kind_requires_eval, eval_required, eval_failed, eval_live_required, eval_quota_exhausted, eval_harness_unavailable, eval_run_not_found, suite_invalid, judge_output_invalid | Evaluations (opt-in) gate this publish or failed. | Fix the suite or the function, or ask an admin about the evaluation policy. |
model_not_allowed, model_mismatch | The model is not on the workspace's allowed list, or does not match the function's. | Pick a model from the catalogue. |
prompt_invalid | The prompt file references a field the input does not have, or is malformed. | Fix the prompt. |
output_invalid, llm_bad_response | The AI answer did not fit the output shape, even after one repair. | Loosen the schema or tighten the prompt. |
llm_refused, llm_unavailable, llm_unreachable, llm_failed | The model refused, or the model service could not be reached. | Retry; check the run's trace; tell Bicycle if it persists. |
classify_labels_missing, classifier_file_invalid, classify_unavailable | The label list is missing or malformed, or the classifier is down. | Fix the labels; retry later. |
budget_exceeded | The run hit its cost, step or time limit. | Read what it could not check; raise the limit only if a real run needs it. |
cancelled | Stopped by a person or a Cancel button. | Nothing, unless it was not you. |
pool_unavailable, runtime_unavailable, runtime_not_found, fn_unavailable, contract_upgrade_required, prices_unavailable | The execution service was not available, or the platform needs an update. | Retry; tell Bicycle with the run link. |
invocation_not_found, invocation_unreadable | Unknown run id, or one you may not read. | Check the id and your workspace. |
lookups_disabled | The retired Lookup kind. | Use an agent with access to the connection. |
connector_not_connected | The viewer has not connected the tool the function or agent reads. | Ask the viewer to connect it in Bicycle. |
volatile_in_deterministic (422) | A function marked "same input, same answer" reads the clock or uses unseeded randomness. | Remove the clock or randomness, or unmark it. |
mcp_exposure_limit | The function's schema or description is too big to expose over MCP. | Shrink it (8 KiB, 16 top-level properties, depth 4, description up to 1000). |
Agents
| Code | Means | Do |
|---|---|---|
queued with queue_position | Not an error: the workspace's agent slots are full and the run is in line. | Show "Queued · N ahead"; keep watching; do not call again. |
agent_busy (429), agent_queue_full | No slot and no room in the queue. | Wait for the retry hint; do not hammer. |
queue_timeout | It waited too long in the queue. | Say so; offer to try again. |
agent_nesting_too_deep (409) | Agents starting agents beyond 3 levels. | Flatten the chain. |
agent_unavailable, agent_error, agent_failed, agent_unauthorized | The agent service was unavailable, failed, or refused the caller. | Retry; check the trace; tell Bicycle with the run link. |
unverified_agent (a warning) | Evaluations are off for this agent. | Normal until someone turns evaluations on. |
Workflows
| Code | Means | Do |
|---|---|---|
revision_conflict (409) | Someone saved a revision after the one you expected (the details say who, when, and whether they touched your paths). | Re-read with workflow_get, re-apply your edits on the new revision, tell the person. Never retry blindly. |
gated_change_needs_person (403), human_publish_required (409) | The revision has gated changes (a send, a query, a model, a "Use", AI text under auto). | A person publishes on the workflow's page. |
person_required (403) | Exposing to agents or MCP, or "send on success", from a token or MCP caller. | Do it in Studio. |
workflow_disabled (409) | The workflow is disabled. | Ask the owner to enable it. |
action_requires_approval | An action send may not run on its own on this workspace. | Switch the step to manual approval (the fix in the answer). |
recipient_domain_not_allowed, external_recipient_needs_approval | The mail policy refuses the domain, or needs a manual step for it. | Use an allowed domain, or a manual approval. |
recipient_not_allowed | On preview, an address outside the allowlist. | Use an allowed address. |
ai_text_unreviewed (a warning) | AI-written text would go out under automatic approval. | Use manual approval, or a person acknowledges it at publish. |
snapshot_app_not_shared, snapshot_render_failed, snapshot_timeout, snapshot_failed | The screenshot could not be taken: the app is not shared with the workspace, or it rendered an error, or it took too long. The send that needed it was skipped. | Share the app; fix the app's error; the author was notified. |
per_row_not_supported | One send per row is not supported in this build. | Send one message that lists the rows. |
send_cap_run, send_cap_daily | Over the per-run or per-day send caps. | Fewer sends; wait for the day to reset. |
idempotency_key_reused | This key was already sent. Not an error: the earlier send stands. | Use a key that names the period. |
cost_cap | The plan estimates the run over $25. | Lower max_cost_usd, fewer rows per call, or a cheaper model. |
cycle | Steps depend on each other in a loop. | Remove the loop. |
dataset_invalid, dataset_not_found, target_unknown | A query, file or artifact the document names does not exist or is malformed. | Fix the name or add the file. |
sql_failed, sql_not_select, sql_param_missing, sql_input_invalid, sql_too_many_rows | The sql step failed: not a SELECT, a missing param, bad input, or too many rows. | Fix the SQL; pass params; limit rows. |
map_too_wide, multi_dimension_node, row_scoped_model | A partition or per-row shape this build does not run. | Simplify the step. |
use_not_supported | The "Use" (who may call it) is not supported here. | Change it. |
run_finished | You tried to cancel or change a run that already ended. | Nothing to do. |
proposal_not_found, proposal_decided, diff_changed | An approval request no longer exists, was already decided, or its content changed. | Read the approvals again. |
store_conflict | Two writers changed the same record. | Re-read and retry. |
validation_unavailable, workflow_runtime_unavailable, workflow_runtime_contract, engine_error, grant_invalid, grant_replayed, grant_revoked, policy_invalid | The workflow service was unavailable, or an internal credential or policy was rejected. | Retry; tell Bicycle with the run link. |
Detect and Explain
| Code | Means | Do |
|---|---|---|
analysis_timeout | The analysis ran over its 30-minute budget. | Narrow the window or the dimensions. |
analysis_abandoned | The job was abandoned (the caller left, or the engine restarted). | Run it again. |
a budget message from analysis_describe | The workspace's daily analysis budget is used up. | Wait for the reset. |
When a coding agent cannot see a tool
Not an error code, but the most common "nothing happens": the agent lists no function_* or fn_* tools. It is on an OAuth sign-in without function scopes. See Connect a coding agent.
When to contact Bicycle
Anything in the "tell Bicycle" rows, or a run that stays Running long after it should have ended. Include the run link from the Runs page, the workspace name, the time and time zone, and the message. Leave out tokens and sensitive rows.