> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/troubleshooting.md).

# FLORA MCP troubleshooting

Fix common FLORA MCP problems in Claude, ChatGPT, Cursor and other clients: connection and sign-in errors, stale tool lists, generation and polling errors, uploads, canvas edits and billing.

Find the symptom, read the cause, apply the fix. Each table below covers one stage of working with [FLORA MCP](https://flora.ai/mcp), from connecting your client to paying for runs. Error text in `code` is what the server returns, so you can search this page for the message your agent shows.

## Connecting and sign-in

| Symptom                                                                                                                               | Cause                                                                                      | Fix                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `curl https://agents.flora.ai/mcp` returns `401` with a `WWW-Authenticate: Bearer … resource_metadata=…` header                       | Normal. The server is up and asks for sign-in                                              | Nothing to fix. A `401` with that header is the health check                                                                                                         |
| `404 Not Found` when adding the server, or Claude says "Your account was authorized, but no MCP server was found at the provided URL" | The URL has a trailing slash or a stray character, such as `/mcp/`, `/mcp.` or `/mcp:`     | Use exactly `https://agents.flora.ai/mcp`, with nothing after `mcp`                                                                                                  |
| "Failed to connect", a timeout or a DNS error                                                                                         | A firewall, VPN or proxy blocks the host, or the URL is mistyped                           | Allow `agents.flora.ai` on your network and check the URL                                                                                                            |
| The sign-in browser tab never opens                                                                                                   | The client couldn't launch a browser                                                       | Look for the sign-in URL in the client's logs or status panel and open it yourself                                                                                   |
| The client asks you to sign in again and again, or calls fail with `401` `invalid_token`                                              | The token expired, was revoked, or isn't being saved                                       | Remove FLORA from the client and add it again (see your client's [install page](https://docs.flora.ai/mcp/install.md)). With `mcp-remote`, also delete `~/.mcp-auth` |
| `401` with an API key                                                                                                                 | The key is wrong, revoked, or not sent as a bearer token                                   | Send `Authorization: Bearer <key>`. Check the key in **Settings → API Keys** and create a new one if it was revoked                                                  |
| `403` "This credential is not authorized to write to the requested workspace…"                                                        | The `workspace_id` isn't one you can write to, or the API key lacks Write permission on it | Call `flora_list_workspaces` and use one of its IDs. For an API key, grant it Write on that workspace                                                                |

| Setting        | Value                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| Server URL     | `https://agents.flora.ai/mcp`                                                                                      |
| Transport      | Streamable HTTP (remote server, nothing to install)                                                                |
| Sign-in        | OAuth with your FLORA account. Headless clients can send a FLORA API key as `Authorization: Bearer <key>` instead. |
| Server name    | `flora`                                                                                                            |
| Check it works | Ask your agent: "List my FLORA workspaces. Don't generate anything."                                               |

## Tools and tool lists

| Symptom                                                                                                                                                                              | Cause                                                                                                       | Fix                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A call to `execute`, `flora_generate`, `flora_get_run`, `get_more_tools` or `search_docs` returns `{"ok":false, "error": "… was replaced by …", "replacement": "…", "retired": "…"}` | The client cached an old tool list, or a script still uses a retired name                                   | Call the tool named in `replacement` and refresh the client's tool list. See [Retired tools](https://docs.flora.ai/mcp/retired-tools.md)                       |
| New tools don't appear after a FLORA update, or the agent describes tools that no longer exist                                                                                       | The client still holds the tool list it loaded when it connected                                            | Refresh the tool list for your client (see [Refresh your client's tool list](https://docs.flora.ai/mcp/retired-tools.md#refresh-the-tool-list-in-your-client)) |
| A tool from these docs isn't in your list                                                                                                                                            | Tool lists vary by account, plan and client. Some tools appear only once your plan or the API supports them | Ask the agent to call `flora_list_tools`, which lists the tools on this connection                                                                             |
| The agent says it has no FLORA tools, but FLORA is connected                                                                                                                         | FLORA isn't turned on for this conversation, or the client hasn't loaded the tools yet                      | Turn FLORA on in the client's tools or connectors menu for this chat, then ask: "List my FLORA workspaces. Don't generate anything."                           |
| "Unrecognized argument(s): … accepts only: …"                                                                                                                                        | The call used an argument name the tool doesn't have                                                        | Use only the names listed in the message. Model options go inside `params`                                                                                     |

## Generating and polling

| Symptom                                                                                                                                                                               | Cause                                                                                                             | Fix                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Run reads return entries with `status: 429` and `retry_after_seconds`, or "Run polling is cooling down or a read is already in progress…"                                             | Polling faster than the poll interval                                                                             | Wait `retry_after_seconds`. Then poll the batch no more than once every `max(15, 2 × run_ids)` seconds. See [Runs](https://docs.flora.ai/mcp/runs.md#poll-a-batch)                                                                                                                   |
| "Rate limit exceeded: each id in run\_ids is one API request against the workspace's per-minute limit…"                                                                               | The workspace hit its per-minute API limit                                                                        | Wait at least 60 seconds, poll less often, and read whole batches in one call instead of one call per run                                                                                                                                                                            |
| `429` `rate_limited` with just "Rate limit exceeded." and no `retry_after_seconds` (for example on a `flora_create_generations` item)                                                 | The per-minute API limit, counted against your credential's default workspace, not the `workspace_id` in the call | Back off about 60 seconds, then retry reads. Don't blindly re-fire creates: read history first and fire only what didn't start                                                                                                                                                       |
| `flora_create_generations` entry fails with `reference_node_ids is only supported for image and model3d generations; "<model>" (type=video) cannot take canvas nodes as inputs here…` | Video generation can't take canvas nodes as references                                                            | Add a video node wired to the image with `flora_add_to_canvas`, then start it with `flora_run_canvas_nodes`. Or pass the image's URL in `params` under the input name `flora_list_models` gives for the model (`image_url` or `image_urls`)                                          |
| `Model "<model>" does not accept image inputs. To animate a canvas image, choose an image-to-video model…`                                                                            | The video model is text-to-video only                                                                             | Pick an image-to-video model from `flora_list_models`                                                                                                                                                                                                                                |
| `Project does not belong to the specified workspace. Pass the workspace this project lives in (see list_projects).`                                                                   | The `workspace_id` doesn't own the `project_id`                                                                   | Leave out `workspace_id` (it's resolved from the project) or pass the project's own workspace                                                                                                                                                                                        |
| `workspace_id does not refer to a workspace you can access.`                                                                                                                          | A guessed or wrong workspace ID                                                                                   | Use an ID from `flora_list_workspaces`                                                                                                                                                                                                                                               |
| `insufficient_credits`, or a run fails with a `BILLING_*` code                                                                                                                        | The balance or a spending limit can't cover the run                                                               | Stop, relay the message and its link, and don't retry. See [Billing](#billing)                                                                                                                                                                                                       |
| `… is not a run id: run ids start with run_…`                                                                                                                                         | A node ID, asset ID or quote entry was polled                                                                     | Poll only the `run_id` values that start tools returned. Quotes have none                                                                                                                                                                                                            |
| A run stays `pending` or `running` far longer than its `estimated_seconds`                                                                                                            | A slow model queue, or a stuck provider job                                                                       | Wait up to 8 × `estimated_seconds` (at least 7 minutes), then tell the user and give them the `run_id` and `canvas_url`. FLORA fails overdue runs on its own, and failed runs aren't charged. See [When a run seems stuck](https://docs.flora.ai/mcp/runs.md#when-a-run-seems-stuck) |
| A create call timed out and you're afraid that retrying will pay twice                                                                                                                | A create that times out may still have started a run, and `flora_create_generations` has no idempotency key       | Read history first: `flora_list_generations` with `project_id` and `include_inputs: true`. Re-fire only prompts with no run. See [After a timeout](https://docs.flora.ai/mcp/runs.md#after-a-timeout-check-before-you-retry)                                                         |
| Some items in a batch failed                                                                                                                                                          | Each item succeeds or fails on its own                                                                            | Retry only the failed items, by error class. Never re-fire the whole batch: the successes already cost money                                                                                                                                                                         |
| A generation fails with "The prompt is N characters, and … accepts up to M", "must be M characters or fewer (this one is N)" or "The prompt is too long for this model"               | The prompt is longer than the model accepts. FLORA refuses it instead of cutting it, and nothing is charged       | Shorten the prompt to the limit in the message, or pick a model with a higher limit                                                                                                                                                                                                  |
| `GPU_PROVIDER_ERROR` or `GENERATION_NO_RESULT` with a message about safety, a refusal or a policy                                                                                     | The model refused the content under a provider error code                                                         | Change the prompt or input. A retry as-is fails the same way                                                                                                                                                                                                                         |

## Uploads

| Symptom                                                                                                                                                      | Cause                                                                                                                                   | Fix                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `… The host refused a server-side fetch; hotlink-protected or login-gated hosts … do this even when the link opens in a browser. Do not retry the same URL…` | The URL answers `401`, `403` or `404` to FLORA's anonymous fetch (common for Midjourney, Discord, Google Drive and Dropbox share pages) | Don't retry it. Call `flora_create_asset` with `source: "signed-url"` and upload the file itself                                |
| `A local file path (such as /mnt/data/…), a file:// URL, or a placeholder cannot be fetched…`                                                                | FLORA can only fetch public HTTPS URLs                                                                                                  | Use `source: "signed-url"`, upload the bytes through `upload_page` or the `upload` descriptor, then call `flora_complete_asset` |
| The upload page says "This upload link has expired"                                                                                                          | `upload_page` links last 15 minutes                                                                                                     | Call `flora_create_asset` again for a fresh link. Don't reuse the old one                                                       |
| `flora_complete_asset` reports the bytes are missing                                                                                                         | The file was never uploaded, or the link expired first                                                                                  | Reserve again with `flora_create_asset`, upload, then complete                                                                  |
| `The source file exceeds the maximum fetch size of 50 MB.`                                                                                                   | FLORA fetches URLs up to 50 MB                                                                                                          | Use `source: "signed-url"` for bigger files                                                                                     |
| An SVG, ZIP or other file type is rejected                                                                                                                   | Only images (JPEG, PNG, WebP, GIF, AVIF, HEIC, HEIF), video (MP4, WebM, QuickTime), audio (MP3, WAV, OGG, M4A) and PDF upload           | Convert it first. Rasterize SVG to PNG                                                                                          |
| A URL to a web page or video player is rejected                                                                                                              | `source` must serve the file's bytes, not a page that displays them                                                                     | Use the direct file URL, or upload the file with `signed-url`                                                                   |
| The agent tries to paste the file as base64                                                                                                                  | Base64 isn't accepted                                                                                                                   | Pass a URL. Files shared in Claude or ChatGPT are already hosted, so pass their URLs directly                                   |

## Canvas

| Symptom                                                                                                                                                                                                                                                 | Cause                                                            | Fix                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `flora_add_to_canvas needs add and/or connect: add is the nodes to create ({ref, type, …}); connect is the edges to wire ({from, to, in?}). Unrecognized argument(s): * — put nodes under add and edges under connect.` after sending a Mermaid diagram | The Mermaid canvas format was removed. The tool takes JSON lists | Send nodes as `add: [{type, ref, prompt, …}]` and edges as `connect: [{from, to}]`                               |
| `Choose one scope: for a subset, omit all and keep node_ids plus optional layout; for the entire canvas, pass all:true alone and omit node_ids and layout…`                                                                                             | `flora_arrange_canvas` got both `node_ids` and `all: true`       | Pass `node_ids` (with an optional `layout`) to arrange some nodes, or `all: true` alone to tidy the whole canvas |
| `"asset_…" is an asset id, not a canvas node id…`                                                                                                                                                                                                       | An asset ID was passed where a node ID belongs                   | Use the node IDs from `flora_get_canvas` or the `created` map                                                    |
| A node was added but nothing generated                                                                                                                                                                                                                  | `flora_add_to_canvas` only adds nodes. It never runs them        | Start the node with `flora_run_canvas_nodes`, using the short ID from the `created` map (not your `ref`)         |
| `flora_run_canvas_nodes` skips a node with `node_not_found`                                                                                                                                                                                             | You passed your own `ref` instead of the ID the canvas assigned  | Use the short IDs (`n7`) or UUIDs from the `created` map or `flora_get_canvas`                                   |
| A `200` response with `warnings`                                                                                                                                                                                                                        | Part of the request was skipped, such as a duplicate edge        | Read the warnings, then check the canvas with `flora_get_canvas`                                                 |
| Duplicate nodes after a timed-out add                                                                                                                                                                                                                   | The add was sent twice                                           | Retry with the same `idempotency_key` so the API rejects the duplicate                                           |
| `revision_conflict` when saving a timeline or deck                                                                                                                                                                                                      | The document changed since you read it                           | Read it again with `flora_get_canvas_node_document` and resend against the new `revision`                        |

## Billing

| Symptom                                                                                                                                                                                              | Cause                                                                                                                                                       | Fix                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `insufficient_credits` (HTTP `402`), or a run fails with `BILLING_NOT_ENOUGH_CREDITS` or `BILLING_FAILED_TO_RESERVE_CREDITS` and a message ending "About FLORA credits: <https://app.flora.ai/home>" | The workspace balance can't cover the run                                                                                                                   | Stop. Relay the message and its link, and don't retry or push an upgrade. In a batch, stop firing                                         |
| A run fails with `BILLING_WORKSPACE_MEMBER_USAGE_LIMIT_EXCEEDED` or `BILLING_ORGANIZATION_MEMBER_USAGE_LIMIT_EXCEEDED`                                                                               | You reached a member limit an admin set                                                                                                                     | Ask a workspace or organization admin. See [Organizations](https://docs.flora.ai/organizations/organizations.md#usage-limits-at-a-glance) |
| A run fails with `BILLING_CREDITS_LIMIT_EXCEEDED` or `BILLING_WOULD_EXCEED_LIMIT`                                                                                                                    | The run would pass a spending limit                                                                                                                         | Ask a workspace admin                                                                                                                     |
| `paid_plan_required` (HTTP `403`) from any tool                                                                                                                                                      | The workspace's plan doesn't include what was asked, such as API access or a feature such as editable share links. It's a plan limit, not a balance problem | Adding balance doesn't fix it. Pick a workspace whose plan includes it, or ask a workspace owner to upgrade                               |
| `flora_get_usage` returns `spend` with `status: "unavailable"` and `entitlement_missing` or `permission_missing`                                                                                     | The plan lacks usage reporting, or you lack billing permission                                                                                              | Relay the reason. It doesn't mean zero spend                                                                                              |
| `flora_get_usage` returns `403` with an API key                                                                                                                                                      | The key lacks Billing permission on that workspace                                                                                                          | Grant the key Billing, or read usage with OAuth                                                                                           |
| Balances look doubled across workspaces                                                                                                                                                              | Workspaces in one organization can share one pool                                                                                                           | Never add `available_cost` across workspaces                                                                                              |
| The final charge differs from the quote                                                                                                                                                              | A quote is an estimate, not a price lock, and expires after 5 minutes                                                                                       | Quote again just before running. Report `charged_cost` from the finished run                                                              |
| `flora_run_action`, `flora_run_canvas_action` or `flora_add_action` returns `403`                                                                                                                    | The plan doesn't include actions, or you can't write to that workspace                                                                                      | Check the workspace with `flora_list_workspaces`. Don't retry the same request                                                            |

See [Cost, balance and limits](https://docs.flora.ai/mcp/cost-and-limits.md) for the full billing rules.

## Still stuck?

Email <support@florafauna.ai> with:

* The client name and version (for example Claude Desktop, ChatGPT or Cursor)
* The time it happened, with your time zone
* The tool name and the exact error text
* Any `run_id`, and the `canvas_url` if you have one

More ways to reach us are on [Help & Support](https://docs.flora.ai/getting-started/help-and-support.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
