Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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

PreviousSystem status

Last updated