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.

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@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/3015ad02f2288ac7. Report an issue: GitHub.

Appendix: source

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

          session,
          connection,
          grant,
          grantRef,
          // OAuth grants declare their canonical oauth.* path. Treating
          // this header projection as a generic credentials.* binding loses
          // the personal secret declaration created by the OAuth callback.
          grantRef.configPath.startsWith("oauth.")
            ? grantRef.configPath
            : `credentials.${ref.name}`,
        );
        headers[ref.key] = `${ref.prefix ?? ""}${value}`;
      } catch {
        await markRemoteConnectionHealth(
          connection,
          "missing_secret",
          "A configured credential secret could not be resolved.",
        );
        throw new ToolGatewayHttpError(
          422,
          "A configured credential secret could not be resolved.",
          "mcp_remote_missing_secret",
          { connectionId: connection.id, credential: ref.name },
        );
      }
    }
    const oauthAccessRef = grant.credentialSecretRefs.find(
      (ref) => ref.configPath === "oauth.access_token",
    );
    if (oauthAccessRef && headers.Authorization === undefined) {
      try {
        const value = await resolveGrantSecretValue(
          session,
          connection,
          grant,
          oauthAccessRef,
        );

View on GitHub (pinned to 3f1d897a7c)