> ## Documentation Index
> Fetch the complete documentation index at: https://www.trybloom.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose Bloom MCP connection, validation, lifecycle, billing, and rate-limit failures.

Bloom MCP tools can return structured content or a tool result marked with `isError`. Read both the content and error state before continuing.

## A tool is missing

Refresh the client's tool list or reconnect the server. Bloom returns the tools currently available to the authenticated account, and that set can vary during a rollout.

Do not call a tool remembered from another account, an earlier session, or copied documentation when it is absent from the current `tools/list` response.

## Authentication fails

* For OAuth, reconnect Bloom and complete the browser sign-in again.
* For an API key, confirm that the header uses `x-api-key` or `Authorization: Bearer`, that the complete key is present, and that the key has not been revoked.
* Confirm the current identity with `bloom_get_account` after reconnecting.

Never paste a secret into a prompt or commit it to a project file. See [Connect Bloom](/docs/mcp/connect) for client-specific configuration.

## A Brand is still processing

`bloom_onboard_brand` returns as soon as creation is queued. Call `bloom_get_brand` with the returned `id` and `wait: true`.

A bounded wait can return `status: "analyzing"`. Repeat the same call with the same ID. Generate only after the Brand reports `ready`.

* `logo_required` means an older Brand or explicit-logo onboarding run needs another logo.
* `failed` includes a machine-readable failure code and a message safe to show to the user.

## An image is still processing

Generation and image transformations return new image IDs immediately. For one image, call `bloom_get_image` with `wait: true`. For several, call `bloom_list_images` once with all `image_ids` and `wait: true`.

Check the returned status. A timed-out wait can return a pending operation, and an accepted operation can later fail. Do not present a result until it is `completed` and has an `image_url`.

## Tool arguments are rejected

Read the current input schema returned by `tools/list`. Common causes include:

* a missing required Brand or image ID;
* an invalid UUID;
* a value outside an enum such as aspect ratio, model, or image size;
* too many reference images or variants; or
* using API-style camelCase fields in an MCP tool that expects snake\_case.

Correct the arguments rather than retrying the same request.

## The request is rate-limited

API-key requests share one request budget across REST and MCP. MCP returns `rate_limit_exceeded` when that key is over its limit. Honor the `Retry-After` header when present; otherwise wait for the documented reset period before retrying.

OAuth access tokens do not use this API-key request limiter. See [Credits and limits](/docs/api/usage-limits).

## Generation cannot start

Before retrying, check:

1. the Brand exists and is `ready`;
2. the source or reference image exists and is accessible;
3. the workspace has enough credits; and
4. the requested size is available to the current plan.

Use `bloom_check_credits` for the selected workspace. Billing failures can include an action URL for purchasing credits, resuming a subscription, or changing plan.

## A local upload cannot reach Bloom

A filesystem path on the agent's machine is not a public image URL.

* In clients that support MCP Apps, use `bloom_open_upload_ui` for images or `bloom_open_logo_upload_ui` for a primary logo.
* In a headless workflow, use `bloom_create_image_upload_url` or `bloom_create_logo_upload_url`, upload the bytes as directed, then use the returned image or Brand result.
* Use `bloom_upload_image` only when the source already has a publicly reachable URL.

Read the live tool descriptions before starting a signed upload; the image and logo flows are intentionally separate.