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

# Troubleshooting

## Import failures

### Swagger/OpenAPI document unreachable in the connect wizard

The connect wizard tried to fetch your Swagger/OpenAPI document and could not reach it. FlowCP fails closed — an app is only created once its document is reachable — so you stay on step 1 (generic provider) or on the import step (Bubble) until it succeeds.

**Generic OpenAPI provider:**

1. Confirm the URL is correct and returns a valid JSON OpenAPI document in a browser or with `curl`.
2. Make sure the document is **publicly reachable** (no VPN, IP allowlist, or auth wall in front of it).
3. Check that the response is under the 5 MB size limit and returns within \~10 seconds.
4. Fix the URL on step 1 and click **Continue to import** again.

**Bubble provider:** this usually means **Hide Swagger Schema** is enabled in your Bubble app settings.

1. Open your Bubble app in the editor.
2. Navigate to **Settings → API**.
3. Uncheck **"Hide Swagger Schema"**.
4. Save your changes.
5. Return to the FlowCP connect wizard and click **Try again**.

If the endpoint is still unreachable after enabling Swagger, confirm that:

* The Bubble API is enabled (check "Enable the Bubble API" on the same settings page).
* Your app has at least one API workflow or data type endpoint published.

### The import status stays at "Pending" for more than a minute

The import job may be stuck in the queue. Try navigating away and back to the import page. If the status has not updated after a few minutes, trigger a re-import from your app's settings.

### Import fails with "Could not fetch Swagger spec"

FlowCP could not reach your Bubble app's Swagger endpoint. Check:

1. **Bubble API is enabled.** Go to Bubble Settings → API and confirm "Enable the Bubble API" is on.
2. **App ID is correct.** The App ID is the subdomain of your Bubble URL — `myapp` for `myapp.bubbleapps.io`. Do not include `.bubbleapps.io`.
3. **Version.** For the **Main** version (or any development version), confirm your Bubble app has that version branch (`/version-<id>/`) with the API enabled.
4. **Custom domain.** FlowCP detects Live custom domains from Bubble's `/api/1.1/meta` when you connect. If Live imports or OAuth still use `*.bubbleapps.io`, open the app's **Settings** and set **Custom domain (Live)** manually, or confirm the Bubble API is enabled so meta is reachable.

### Import fails with "OpenAPI 3.x required" or "Invalid OpenAPI spec"

Bubble publishes **Swagger 2.0** at `/api/1.1/meta/swagger.json`. FlowCP converts that format automatically during import. If you still see a validation error:

The Bubble API returned a document that FlowCP could not parse. This can happen if:

* The API is configured but has no endpoints defined
* Your Bubble branch outputs a non-standard spec format

Enable at least one API endpoint in Bubble and re-import.

### Re-import fails with "URL returned HTTP 404" (OpenAPI apps)

If a generic OpenAPI app imported successfully before but a later re-import fails with **URL returned HTTP 404**, its stored Swagger URL is pointing at the wrong location. Open the app's **Settings**, find the **Swagger URL** card, re-enter the correct OpenAPI/Swagger document URL, and click **Save Swagger URL**. FlowCP verifies the URL is reachable and re-imports your tools from it.

***

## OAuth errors

### "OAuth provider not configured"

The client ID and secret have not been saved. Open the **OAuth** tab and complete the configuration before testing the flow. For a generic provider, make sure the **authorize** and **token** URLs are filled in too.

### Authorization completes with your provider but redirects to an error page

The redirect URI registered with your provider does not match the one FlowCP expects. Copy the **FlowCP OAuth redirect URI** from the OAuth page and add it exactly (including protocol and path) to your provider's allowed redirect URLs. For Bubble, that's Settings → API → 3rd Party OAuth → Allowed redirect URLs.

### ChatGPT (web) shows "There was a problem connecting" right after sign-in

You add the connector in ChatGPT on the web (`chatgpt.com`), complete the sign-in with your provider, get redirected back to ChatGPT, and then see *"There was a problem connecting FlowCP. Try again later."*

ChatGPT on the web runs in the browser, so the requests it makes back to FlowCP to finish connecting (the OAuth token exchange and the MCP handshake) are cross-origin. FlowCP now sends the cross-origin (CORS) headers those endpoints need, so this should succeed. If you still hit it:

1. Confirm the server status is **published** on the Publish page.
2. Confirm **OAuth** is configured for the app (client ID/secret saved, and for a generic provider, the authorize and token URLs).
3. Remove and re-add the connector, then retry — ChatGPT caches connector state.
4. If it still fails, open your browser's DevTools → **Network** tab and reproduce. The failed request names the exact endpoint and status code; include that when you contact support.

### "Token expired" errors in execution logs

The user's access token has expired. FlowCP will automatically signal the AI client to re-authorize (the AI client shows an OAuth prompt). If re-authorization does not happen automatically:

* Ask the user to restart their AI client session to trigger a new authorization prompt.
* If the client secret was rotated without updating FlowCP, update it on the OAuth page — new authorizations will use the updated credentials.

***

## Publish errors

### Publish button is disabled

At least one enabled tool is classified `destructive` and does not have **Require confirmation** turned on. The publish page lists the tool names. Go to the Tools tab, find each listed tool, and turn on **Require confirmation**.

### Server status shows "published" but AI client does not see the tools

1. **Restart the AI client.** Most clients only load MCP config on startup.
2. **Check the config URL.** The URL in your config should point to the MCP runtime (e.g. `runtime.flowcp.io/mcp/<server-id>`), not the FlowCP dashboard or API server.
3. **Verify tools are enabled.** At least one tool must be enabled for the server to return a non-empty tools list.

### Server URL shows "MCP runtime URL not configured" (self-hosted)

The dashboard renders each server's public endpoint from its own `MCP_RUNTIME_PUBLIC_URL` environment variable. If that variable is missing on the **web/dashboard** service, the Servers, MCP-clients and Publish pages show a "MCP runtime URL not configured" notice instead of a URL.

Set `MCP_RUNTIME_PUBLIC_URL` to your MCP runtime's public origin (e.g. `https://mcp.example.com`) on the web service and restart it — the value is read at runtime, so no rebuild is needed. In the bundled docker-compose stack all services share one `.env`, so this only bites split deployments where the web, API and runtime run as separate services. See [Self-host the platform](/guides/self-host-platform.md#ports).

***

## MCP tool call failures

### Tool call returns "tool\_disabled"

The tool was enabled at publish time but has since been disabled. Re-enable it from the Tools tab.

### Tool call returns "token\_missing"

The calling user has not authorized FlowCP yet. The MCP client should surface an authorization URL — direct the user to visit it.

### Tool call returns a 401

The user's access token is invalid or expired. FlowCP automatically signals the AI client to re-authorize — the AI client should present an OAuth prompt. Ask the user to complete the re-authorization flow in their AI client.

If the AI client does not show a prompt, restarting it usually triggers the re-authorization.

### Tool call returns a 403

The user's account does not have permission to perform the action. This is your API enforcing its own access rules — FlowCP cannot override them. (For Bubble, check the app's privacy settings for the relevant data type.)

***

## Still stuck?

Open an issue at the FlowCP support channel or contact your account manager. Include:

* Your workspace ID
* The app ID and server ID from the FlowCP URL
* The error code and timestamp from the execution logs