ComposioHQ/composio · error · ComposioFailedToCreateConnectedAccountLink

Failed to create connected account link

Error message

Failed to create connected account link

What it means

Generic ComposioFailedToCreateConnectedAccountLink: the underlying API call to create the connection link failed for any reason other than the ACL-only-for-shared case. The original error is attached as cause.

Source

Thrown at ts/packages/core/src/models/ConnectedAccounts.ts:448

        response.redirect_url
      );
      return connectionRequest;
    } catch (error) {
      // Caller-initiated cancellation must surface as the typed error,
      // not get remapped to ComposioFailedToCreateConnectedAccountLink below.
      if (error instanceof ComposioRequestCancelledError) {
        throw error;
      }
      // The server rejects ACL on PRIVATE connections — surface that as a
      // typed error so callers can `instanceof` instead of grepping messages.
      if (
        error instanceof BadRequestError &&
        typeof error.message === 'string' &&
        error.message.includes(ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT)
      ) {
        throw new ComposioAclOnlyForSharedError(error.message, { cause: error });
      }
      throw new ComposioFailedToCreateConnectedAccountLink(
        'Failed to create connected account link',
        {
          cause: error,
        }
      );
    }
  }

  /**
   * Waits for a connection request to complete and become active.
   *
   * This method continuously polls the Composio API to check the status of a connection
   * until it either becomes active, enters a terminal error state, or times out.
   *
   * @param {string} connectedAccountId - The ID of the connected account to wait for
   * @param {number} [timeout=60000] - Maximum time to wait in milliseconds (default: 60 seconds)
   * @returns {Promise<ConnectedAccountRetrieveResponse>} The finalized connected account data
   * @throws {ComposioConnectedAccountNotFoundError} If the connected account cannot be found

View on GitHub (pinned to 64b1b85502)

Solutions

1. Inspect error.cause for the HTTP status/body
2. Verify the authConfigId exists (composio.authConfigs.get)
3. Check the redirectUrl is a valid, allowlisted https URL
4. Verify API key and environment (api.composio.com vs staging) match

await composio.authConfigs.get({ toolkits: [authConfigId] }); // confirm config exists before linking

const isLinkFailed = (e: unknown): boolean => e instanceof ComposioFailedToCreateConnectedAccountLink;

try { await ca.link(id, opts); } catch (e) { if (e instanceof ComposioFailedToCreateConnectedAccountLink) { log(e.cause); /* inspect HTTP error, fix config, retry once */ } }

When it happens

Trigger: Any backend failure during link() — invalid authConfigId, expired/invalid API key, malformed redirectUrl, network errors, or backend 4xx/5xx responses not matching the ACL fragment.

Common situations: Wrong API base URL or key in dev environments, typo'd auth config slug, redirect URL not allowlisted on the backend.

Related errors

• Multiple connected accounts found for user ${userId} in auth
• ${error.message (upstream BadRequestError: ACL only allowed
• Failed to list MCP servers
• Failed to update MCP server {server_id}
• Failed to delete MCP server {server_id}

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/82465fe9e73bb35c. Report an issue: GitHub.