Troubleshooting

Find your symptom. Each entry says what the cause actually is and what to do about it.

Start here: three checks that isolate the problem

Run them in order. Each one rules out a layer.

Connection problems

The server will not connect at all

405 method_not_allowed on a GET

Expected, not a fault. The hosted endpoints are stateless JSON-RPC over POST. A GET returns 405 with an Allow: POST, OPTIONS header. If your client only ever gets 405, it is probing rather than speaking MCP — confirm it is registered as a streamable-HTTP MCP server rather than a plain web hook.

403 access_denied mentioning Origin

Your browser-based client is sending an Origin header Gavana does not accept. The hosted endpoints allow https://chatgpt.com, https://claude.ai, and the Gavana origin itself, plus anything the deployment explicitly permits.

Non-browser clients send no Origin header and are unaffected — so if you are seeing this from a terminal client, something in between is adding the header.

The local stdio server will not start

Missing or unexpected tools

A tool the docs mention is not in my client’s list

find_video_models returns 403 insufficient_scope

The hosted tools reference lists it as read-only, which is accurate — looking up a model mutates nothing. It still requires the video:generate scope, because discovering video models is part of the generation path. A token without that scope is refused before the handler runs.

The tool list changed after I edited the URL

Some clients keep the original OAuth grant when you edit a server’s URL in place. Remove the server and add it again rather than editing:

claude mcp remove gavana && claude mcp add --transport http gavana https://app.gavana.ai/mcp

Authentication and scope errors

401 invalid_token

The token is missing, malformed, expired, or revoked.

• Hosted: reconnect the client and complete OAuth again.
• Local: Agent Access tokens default to Never expiry. If this token was created with a custom 1–90 day expiry, create a replacement and update the client’s environment.
• Check you are not passing a token in a URL or a custom header. Gavana accepts bearer tokens in the Authorization header only.

403 insufficient_scope

The token is valid but lacks a scope the tool needs. The error message names the missing scopes, and the WWW-Authenticate header repeats them.

The scope check happens before the handler runs, so nothing partial occurred and no paid work started.

Common cases:

Token creation rejects my scope selection

Scope dependencies are enforced at creation, not silently added:

• canvas:write requires canvas:read
• element:write requires element:read
• image:generate requires canvas:read, canvas:write, and asset:read
• video:generate requires canvas:read and asset:read

The error names exactly which are missing. The token creation form selects dependants for you.

It works, but touches the wrong account

You approved a different Gavana account during OAuth. Disconnect and reconnect, watching which account you sign in as. For a local token, the token itself is bound to the account that created it — create one from the right account.

Canvas errors

409 on canvas_apply_batch or a canvas_validate dry-run

The canvas changed after you read the revision you passed. Someone else’s work is now in the graph.

Two 409s in a row means someone is actively working in that canvas. Say so and stop rather than racing them.

404 on a canvas or node

The handle is wrong. Get canvas handles from canvas_list and node handles from canvas_get. Do not reconstruct a handle from parts, and do not truncate one to fit.

The batch was rejected and nothing happened

Correct behaviour. canvas_apply_batch is atomic — one invalid operation means no partial graph. The error names the failing operation.

Fix that operation. Do not resend the batch minus the failure unless dropping it is genuinely your intent.

malformed_section in the validation output

A Section is a text node with metadata.isSection: true, at least 200 × 160. Any other node type, or a smaller one, is an error.

Rejected for writing metadata.content

Media is server-owned. You cannot write image or video bytes, storage keys, or arbitrary media URLs into node metadata. A non-empty metadata.content is rejected when the node is, or is becoming, an image or video.

Use save_image_to_canvas or a generation tool.

canvas_validate says summary.truncated

Findings hit the 50-per-code cap, or overlap analysis gave up. Overlap detection buckets nodes into a 2,048-unit grid, refuses any node spanning more than 64 cells, and stops after 100,000 comparisons.

Fix the findings you can see and run it again — the next pass surfaces what was cut. Meanwhile, say your report is incomplete.

summary.passed is true but something is still wrong

passed only means zero errors. reviewRequired is the field to read: it is true when there are errors, or warnings, or truncation.

Paid work looks stuck

This is the section where the wrong move costs money.

A paid tool returned while still queued

This is normal and it is not a failure. The tool waited waitSeconds — 45 by default, 50 maximum — and handed you a resumable handle because the work was not finished.

Poll instead:

Polling is free. Call it again while the status is queued or running.

Raising waitSeconds does not make generation faster. It only changes how long the tool blocks before giving you the handle.

A paid run failed terminally

Report it and stop. Ask for fresh intent before any new attempt.

Do not automatically retry a terminal failure, a timeout, a disconnect, or an ambiguous provider response with a new key. The idempotency key protects against a duplicate request; it does not make a second deliberate attempt free.

400 “not a video generation” or “not a reusable workflow run”

You passed the wrong kind of handle. get_video_job takes a job: handle from generate_video; get_canvas_workflow_run takes a run: handle from run_canvas_workflow. They are not interchangeable.

A run succeeded but I cannot find the image

A run reporting success is not the same as durable canvas content. Read the canvas:

{ "name": "canvas_get", "arguments": { "canvasId": "canvas:abc123:product-shots" } }

Check the output node exists, is of type image, and carries server-owned media rather than being an empty placeholder. A video job in particular may return a protected download link without materialising a native video node — report what the server actually returned rather than assuming durability.

The agent started generating without being asked

The server’s instructions tell the model to require explicit current-turn intent, but instructions are not enforcement. The hosted endpoint registers the paid tools and the token holds the scopes that can run them.

If this happened, treat it as a contract break: tell the agent to stop, and require explicit current-turn approval before any further paid call. For unattended local work, set GAVANA_MCP_READ_ONLY=true or issue a token without generation scopes.

Image errors

Getting help

When you report a problem, include:

• The X-Request-ID from the failing response. It identifies the exact request in Gavana’s logs.
• The tool name and the HTTP status or error code.
• Which server you are on — hosted /mcp, or local stdio.
• The canvas handle, if the problem is canvas-specific.

Related