paperclipai/paperclip · error · ToolGatewayHttpError
Gateway bearer token is expired or invalid
Error message
Gateway bearer token is expired or invalid
What it means
recordNamedGatewayAuthFailure is the shared failure recorder for named-gateway bearer authentication: it resolves the gateway by id/public id, derives the token identity (id or hash) for the failure counter, and always throws so callers get a 401-style terminal result. The message itself is the generic invalid-expired-token sentinel used after the failure has been counted and audited.
Source
Thrown at server/src/services/tool-gateway.ts:3654
}
}
} catch {
for (const { reject } of pending.values()) {
reject(stdioProtocolError("Local stdio MCP server returned invalid JSON", {
connectionId: input.connection.id,
catalogEntryId: input.entry?.id ?? null,
}));
}
pending.clear();
}
}
newline = stdout.indexOf("\n");
}
});
child.stderr.on("data", (chunk: string) => {
stderr = `${stderr}${chunk}`.slice(-4_000);
});
const exitPromise = new Promise<void>((resolve, reject) => {
child.on("error", (error) => {
const gatewayError = new ToolGatewayHttpError(502, "Local stdio MCP command failed to start", "local_stdio_spawn_failed", {
connectionId: input.connection.id,
templateId: input.template.templateId,
message: error.message,
});
for (const { reject: rejectPending } of pending.values()) {
rejectPending(gatewayError);
}
pending.clear();
reject(gatewayError);
});
child.on("exit", (code, signal) => {
if (pending.size === 0) {
resolve();
return;
}
for (const { reject: rejectPending } of pending.values()) {View on GitHub (pinned to 01ad858492)
Solutions
- Obtain a fresh gateway bearer token; the current token is expired or invalid.
Defensive patterns
Strategy: try-catch
When it happens
Trigger: Thrown at server/src/services/tool-gateway.ts:3513 when the library encounters an invalid state.
Common situations: See trigger scenarios.
Understand the failure class
- Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.
AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18).
Data as JSON: /api/errors/2339bf69962c3714.
Report an issue: GitHub.