> ## Documentation Index > Fetch the complete documentation index at: https://docs.rainbrand.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Diagnose Rainbrand MCP connection, validation, lifecycle, billing, and rate-limit failures. Rainbrand 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 your client's tool list. If the tool is still missing, reconnect Rainbrand and complete authentication again. Only call tools listed in the refreshed `tools/list` response. ## Authentication fails * For OAuth, reconnect Rainbrand 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 `get_account` after reconnecting. Never paste a secret into a prompt or commit it to a project file. See [Connect Rainbrand](/mcp/connect) for client-specific configuration. ## An existing connection still shows Bloom A connection added with the former `https://mcp.trybloom.ai/mcp` address or a `bloom` server name keeps working with the same account, brands, and tools. You don't need to reconnect. To show the new name, remove the old connection, then [add Rainbrand](/mcp/connect) with `https://mcp.rainbrand.com/mcp`. ## A brand is still processing Call `get_brand` with the returned `brand_session_id` and `wait: true`. If it returns `analyzing`, repeat the same read. A timeout leaves analysis running; do not create another brand to check progress. Waiting applies only to current initialization. Omit `version_id` when checking progress: a version-specific read returns the saved snapshot immediately. `timeout` has no effect without `wait: true`. For a newly created brand, stop waiting when the status is `ready` or `failed`. A failed brand includes a machine-readable failure code and a message safe to show to the user; unavailable canonical fields are omitted. An existing legacy Visual DNA brand can return `logo_required`. Stop waiting and [create a new brand from sources](/guides/create-brand) if needed; MCP cannot replace its logo. ## A Brand Edit is still preparing If `create_brand_edit` or `continue_brand_edit` returns `preparing`, call `get_brand_edit` with the same `edit_id` and `wait: true`. Repeat that read if it times out while preparation continues; do not start another edit to check progress. Stop waiting when the edit requests input, produces a candidate, or ends in another state. Follow the corresponding action in [Edit a brand](/guides/edit-brand). ## An image is still processing Generation and image transformations return new image IDs immediately. For one image, call `get_image` with `wait: true`. For several, call `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 ID 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](/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 `check_credits` for the selected workspace. Billing failures can include an action URL for purchasing credits, resuming a subscription, or changing plan. When Model Gateway billing is enabled, a billing rejection returns a tool result marked with `isError`. Its text explains the failure and includes a pricing link. Follow that explanation before retrying; see [Credits and limits](/api/usage-limits#model-gateway-billing) for eligibility and charges. If `check_credits` reports that the workspace's billing account isn't set up, retrying won't help. Contact [support@rainbrand.com](mailto:support@rainbrand.com) with the billing ID from the message. ## A local upload cannot reach Rainbrand A filesystem path on the agent's machine is not a public URL. Private attachment URLs from the host client are not supported. Use the [upload guide](/guides/upload-files) to choose between the MCP picker, direct HTTP upload, and a public HTTPS URL. If the client cannot execute the PUT returned by `create_upload_urls`, switch to an available alternative. For picker errors: * Pass exactly one destination to `open_upload_ui`: `workspace_id` for staging or `brand_session_id` for saving images to a Brand Library. Use `workspace_id: null` to stage in your personal workspace. * Resolve a staging reference with `get_file_picker_handoff` before using it. Use the verified upload IDs with Rainbrand tools that accept them in the returned workspace, and each file's temporary `url` where a generation model input expects a file URL. * If images were saved to a Brand Library but the agent cannot see them, use the final Library image IDs in the picker's chat message. These are ready to use without resolving a staging reference. * If some files fail, retry them or let the user explicitly Continue with successful files. Never include failed uploads, and do not start onboarding after cancellation or when no files succeeded. * Upload expired files again. For a workspace mismatch, stage the files in the brand's workspace. For a new brand, use the same workspace for staging and onboarding. Follow the [workspace instructions](/guides/upload-files) when passing a picker handoff to another tool. Staging alone does not finish the task. Check the consuming tool's result before reporting success. For a logo change, follow [Edit a brand](/guides/edit-brand) after saving the image to the Brand Library. Older Visual DNA brands do not support logo replacement. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.