Troubleshooting#
Contents
“agent-token-required”#
The assistant reached the server without signing in. Finish sign-in in your assistant (in Claude Code, /mcp; in Codex, codex mcp login bitebox). Do not paste a token into the configuration.
Connected, but no tools#
Saved configuration, finished sign-in and loaded tools are separate steps. If the first two worked but the chat has no Bitebox tools or says the server is unknown, start a new chat or restart the assistant, then call workspace_context again. That alone is not a sign-in problem.
A tool from the changelog is missing#
The MCP changelog lists a tool or an argument that your assistant does not have, or a tool refuses an argument the changelog describes. Your assistant still has the tool list from when it connected, because Bitebox does not tell an open connection that its tools changed. Reconnect it. Some tools are only for accounts where a feature is on, and the changelog says which.
Access expired or revoked#
The server answers agent-grant-rejected with “This agent token was revoked.” or “This agent token has expired.” Disconnect and reconnect the server in your assistant to sign in again. A revoked assistant stays off until you connect it again.
“agent-capability-required”#
The tool needs a permission this grant does not have, for example “generate_run needs generate…”. Only you can widen a grant: click Edit on that assistant in the Canvas MCP tab and allow the permission. An assistant should ask you, not look for another way in.
A project answers “Not found.”#
Either the project id is wrong or the project is outside the projects you picked. Both answer the same. Check with project_list. To add a project, click Edit on the assistant in the Canvas MCP tab.
Wrong address or environment#
Use https://mcp.bitebox.gg/api/mcp. The Canvas address, an address without /api/mcp, or a team test server will not work with your Bitebox account. Access from one server is “not valid here” on another: remove the old entry and connect to the address above. The server only answers POST requests, so opening the address in a browser shows an error; that is expected.
Budget refused#
agent-budget-exceeded means the run is quoted above what is left of today's budget. Nothing ran and nothing was charged. Approve the spend on the confirm card in the Canvas and have the assistant retry with the same runId, raise the budget with Edit in the Canvas MCP tab, or wait for the reset at midnight UTC.
Approval needed#
agent-spend-approval-required means you turned on Ask before each run and have not approved this run yet. Nothing ran and nothing was charged. Open the approval link the assistant gives you, or open the project in the Canvas, and answer the card. Then the assistant sends the run again. agent-spend-declined means you declined it. To stop the cards, turn the setting off with Edit in the Canvas MCP tab.
Reference clip too long or too short#
Each video model takes reference clips of a set length. When a wired clip is outside it, the quote is refused before anything is held or charged. The message names the clip by its number among the wired videos (“Reference video 2”, the same clip the prompt calls Video 2), the model, and that model's limit. Trim the clip or wire another, then quote again. The limits are listed under prompting tips. A source clip has a limit too: Flux 3 edits or continues clips under 15 seconds. That message starts “The source clip is”.
If the model refuses a clip for its length after the run started, the answer says which clip to change. GEN-207 means no credits were charged. GEN-211 means the credit hold is kept until the charge is confirmed, and the answer ends “Your credits will come back.” It carries a reference id for support. Change the clip before you run again.
GEN-206 means the model's content filter refused the run, and the answer says what to change. A run that made nothing for any other reason answers GEN-209: nothing to change, try again.
MCP unavailable#
If every token is refused as “not valid here”, sign-in pages answer “not found”, or the server answers agent-grant-unavailable, Bitebox has paused or cannot reach agent access. Nothing is wrong with your setup. Wait and try again later rather than creating new connections.
Revision conflict#
Someone saved the project after your assistant read it. Bitebox reapplies the batch on the newest revision; if both changed the same property, the answer is conflict and says which value was kept. Everything else in the batch was saved, so do not send the whole batch again. Read the project with document_get and send only that property again if it should replace the saved value.
The same applies when the project is open in the Canvas while your assistant writes. A Canvas save keeps the assistant's changes, and the Canvas shows them as soon as that save finishes. If both changed the same property, the Canvas value is kept.
More help#
- Canvas: open the MCP tab on your home page to connect or revoke assistants.
- Builder guide: order of work, wiring, media and the 9:16 format.
- Acceptable Use Policy and Terms: what you and your assistant may make and publish.
A clip review timed out#
A media_review audit runs for about a minute, so a client with a shorter timeout can lose the answer. The credits are held. Have the assistant call media_review again with the same arguments. For 24 hours that call answers the same audit and charges nothing. review-running means it is still going, so try again in about 30 seconds. If a verdict is incomplete, the next call is a new paid audit. To pay for a new audit of the same clip, pass fresh: true.
A panel_watch runs for minutes and recovers in the same way: call it again with the same arguments. If a watch failed, its credits were spent and the next call is a new paid watch.