paperclipai/paperclip · error · ToolGatewayHttpError

mcp_remote_missing_secret

mcp_remote_missing_secret

Error message

A configured credential secret could not be resolved.

What it means

Credential resolution failure while building request headers for a tool connection: secrets.resolveSecretValue could not resolve one of the connection's credentialRefs (placement=header) — the secret is missing, its version is unavailable, or access was denied for this consumer. The masked 500 indicates an operator-side secret configuration problem, not caller input.

Source

Thrown at server/src/services/tool-gateway.ts:2493

    const passthroughAllowlist = [
      ...stringArray(passthrough.allow),
      ...stringArray(passthrough.allowedHeaders),
      ...stringArray(rawPolicy.allowedPassthroughHeaders),
    ]
      .map(headerName)
      .filter((name): name is string => Boolean(name))
      .filter((name) => !isSensitivePassthroughHeader(name));

    const metadata = asRecord(rawPolicy.metadata) ?? {};
    const metadataHeaders = [
      ...stringArray(metadata.forward),
      ...stringArray(metadata.headers),
      ...stringArray(rawPolicy.forwardContextHeaders),
    ].filter((value): value is HeaderPolicyConfig["metadataHeaders"][number] =>
      value === "company_id"
      || value === "agent_id"
      || value === "issue_id"
      || value === "project_id"
      || value === "run_id"
      || value === "gateway_session_id"
      || value === "correlation_id",
    );

    return {
      staticHeaders: parsedStaticHeaders,
      passthroughAllowlist: [...new Set(passthroughAllowlist)],
      metadataHeaders: [...new Set(metadataHeaders)],
    };
  }

  function readOnDemandToolsEnabled(connectionOrConfig: typeof toolConnections.$inferSelect | Record<string, unknown>): boolean {
    const config = "config" in connectionOrConfig ? asRecord(connectionOrConfig.config) ?? {} : connectionOrConfig;
    const raw = asRecord(config.onDemandTools) ?? asRecord(config.loadToolsOnDemand);
    return config.onDemandTools === true || config.loadToolsOnDemand === true || raw?.enabled === true;
  }

View on GitHub (pinned to 01ad858492)

Solutions

1. Fix the connection's credential reference: the named secret is missing from the secret store. Reconfigure the credential or create the secret.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:2397 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/3015ad02f2288ac7. Report an issue: GitHub.