different-ai/openwork · error

MCP_LIFECYCLE_DEADLINE

MCP_LIFECYCLE_DEADLINE

Error message

MCP_LIFECYCLE_DEADLINE

What it means

MCP_LIFECYCLE_DEADLINE is returned when the operation failed because ExternalMcpLifecycleDeadlineError fired — the gateway's bounded lifecycle deadline expired — or because the enterprise client raised its own matching RequestTimeout. The marker check runs before JSON-RPC error codes are read so the client's own timeout is not misattributed to the provider. It is retryable and owned by the provider admin: the provider was too slow to complete the full MCP lifecycle (or one tool call) within the deadline.

Source

Thrown at ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts:1179

      phase: "NETWORK_TCP",
      category: "network_failure",
      code: `MCP_${normalizedCode}`,
      retryable: normalizedCode === "ECONNRESET" || normalizedCode === "ETIMEDOUT" || normalizedCode.startsWith("UND_ERR_"),
      actionOwner: "network_admin",
      operatorAction: "Verify provider allowlists, firewall rules, proxy requirements, and service availability from Den.",
    }
  }
  return null
}

function classifyError(error: unknown, fallbackPhase: ExternalMcpDiagnosticPhase): Classification {
  // The enterprise client aborts with a RequestTimeout MCP error of its own, so
  // check for our marker before any JSON-RPC code is read as the provider's.
  if (error instanceof ExternalMcpLifecycleDeadlineError || isEnterpriseMcpLifecycleDeadline(error)) {
    return {
      phase: fallbackPhase,
      category: "lifecycle_deadline",
      code: "MCP_LIFECYCLE_DEADLINE",
      retryable: true,
      actionOwner: "provider_admin",
      operatorAction: fallbackPhase === "MCP_TOOL_EXECUTION"
        ? "Retry the capability, and reduce provider latency for this tool if it keeps running past the bounded deadline."
        : "Reduce provider latency or catalog pagination so the complete MCP lifecycle finishes within the bounded deadline, then retry.",
    }
  }
  if (error instanceof ExternalMcpResponseBodyLimitError) {
    return {
      phase: fallbackPhase,
      category: "response_too_large",
      code: "MCP_RESPONSE_BODY_LIMIT",
      retryable: false,
      actionOwner: "provider_admin",
      operatorAction: "Reduce the provider response size, tool catalog, or event-stream payload before retrying.",
    }
  }
  if (error instanceof PrivateUrlError) {

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Retry the capability; transient provider slowness often clears on a subsequent attempt.
2. If tool execution repeatedly exceeds the deadline, reduce provider latency for that tool (faster backend, smaller inputs, async job pattern).
3. For discovery-phase deadlines, reduce catalog size or pagination so the complete MCP lifecycle finishes within the bounded deadline.

Example fix

// before: one giant unpaginated discovery that blows the deadline
const tools = await listAllTools(client) // thousands of tools
// after: bounded pagination
const tools = []
for await (const page of listToolsPaginated(client, { pageSize: 50 })) tools.push(...page)

// estimate catalog size before a full lifecycle to avoid deadline blowouts
const probe = await client.listTools({ pageSize: 1 })
if (probe.totalCount > 500) {
  throw new Error(`catalog too large (${probe.totalCount}) for single lifecycle deadline; paginate`)
}

function isLifecycleDeadline(d: { code: string }): boolean {
  return d.code === 'MCP_LIFECYCLE_DEADLINE'
}

try {
  return await runCapability(req)
} catch (e) {
  if (isLifecycleDeadline(e.diagnostic)) {
    // retryable: retry once; if it recurs, reduce provider latency or paginate discovery
    return await runCapability(req)
  }
  throw e
}

When it happens

Trigger: A tool execution (MCP_TOOL_EXECUTION) or a full catalog lifecycle (initialize + discovery) exceeding the bounded deadline, throwing ExternalMcpLifecycleDeadlineError; or an enterprise MCP client timeout (RequestTimeout) being detected via isEnterpriseMcpLifecycleDeadline.

Common situations: Slow provider backends or models making individual tool calls run for minutes; enormous tool catalogs requiring paginated discovery that exceeds the lifecycle budget; provider outages or degraded performance; network latency between gateway and provider.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Authorization for ${input.connectionName} did not finish. Co
• Connection closed before the tool response completed
• MCP_SESSION_NOT_FOUND
• MCP_HTTP_429
• Agent context diagnostics timeout must be between 1 ms and 3

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