different-ai/openwork · error · McpOAuthStartError

Failed to start OAuth (${response.status}).

Error message

Failed to start OAuth (${response.status}).

What it means

Same non-2xx start-OAuth failure as its sibling, but without the 'configuration_required' errorCode: the failure is wrapped in McpOAuthStartError with debug details (status, payload-derived errorCode) for the UI to display. This is the generic OAuth handshake-start failure path.

Source

Thrown at ee/apps/den-web/app/(den)/dashboard/_components/mcp-connections-data.tsx:895

  const { orgId } = useOrgDashboard();

  return useMutation({
    mutationFn: async (connectionId: string): Promise<{ status: "connected" | "needs_auth"; authorizeUrl: string | null }> => {
      const { response, payload } = await requestJson(
        `/v1/mcp-connections/${encodeURIComponent(connectionId)}/connect/start`,
        { headers: getOrgScopeHeaders(requireOrgId(orgId)) },
        20000,
      );
      if (!response.ok) {
        const details = mcpOAuthStartDebugDetails(payload, response.status);
        const requestError = getRequestError(payload, response, `Failed to start OAuth (${response.status}).`);
        if (details.errorCode === "mcp_oauth_configuration_required") {
          throw new McpOAuthConfigurationRequiredError(
            requestError.message,
            details,
          );
        }
        throw new McpOAuthStartError(requestError.message, details);
      }
      return payload as { status: "connected" | "needs_auth"; authorizeUrl: string | null };
    },
  });
}

export function useDisconnectMyProviderAccount() {
  const queryClient = useQueryClient();
  const { orgId } = useOrgDashboard();

  return useMutation({
    mutationFn: async (connection: Pick<ExternalMcpConnection, "id" | "nativeProviderKey">): Promise<string> => {
      const path = isNativeProviderConnectionId(connection.id, connection.nativeProviderKey)
        ? `/v1/oauth-providers/${encodeURIComponent(connection.id)}/disconnect`
        : `/v1/mcp-connections/${encodeURIComponent(connection.id)}/disconnect-my-account`;
      const { response, payload } = await requestJson(
        path,
        { method: "POST", headers: getOrgScopeHeaders(requireOrgId(orgId)) },

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Read details/errorCode on the thrown McpOAuthStartError to identify the specific upstream cause
2. Verify the connectionId still exists (refetch mcpConnectionQueryKeys.all) and retry
3. Check Den server logs for the outbound call to the MCP authorization server
4. Retry after confirming the MCP server is reachable — transient 5xx/502 resolve on retry
5. If persistent 4xx, the stored connection/issuer data is stale: disconnect and re-add the connection

// pre-check the connection still exists
const conn = queryClient.getQueryData<UpdatedMcpConnection>([...mcpConnectionQueryKeys.all, connectionId]);
if (!conn) { refetchConnections(); return; }

function isMcpOAuthStartError(e: unknown): e is McpOAuthStartError {
  return e instanceof McpOAuthStartError;
}

try {
  await startOAuth.mutateAsync(connectionId);
} catch (e) {
  if (e instanceof McpOAuthStartError && isTransient(e.details)) {
    await retryWithBackoff(() => startOAuth.mutateAsync(connectionId), 3);
    return;
  }
  showToast({ variant: 'error', title: 'OAuth start failed', description: e instanceof Error ? e.message : String(e) });
}

When it happens

Trigger: POST to start MCP OAuth returns non-2xx whose payload errorCode is anything other than 'mcp_oauth_configuration_required' (e.g. connection not found, provider unreachable, invalid state, upstream 502 from the MCP server).

Common situations: MCP server temporarily down or timing out upstream; connection was deleted between listing and OAuth start; bad request payload (malformed connectionId); transient 5xx during provider maintenance.

Related errors

• Could not start ${action.connectionName} authorization.
• mcp_oauth_configuration_required
• OpenWork-managed MCP OAuth is currently available for local
• OpenWork-managed OAuth requires a remote MCP URL.
• Authorization for ${input.connectionName} did not finish. Co

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/5c8f5b140728922c. Report an issue: GitHub.