paperclipai/paperclip · error · ToolGatewayHttpError

vercel_connect_unavailable

vercel_connect_unavailable

Error message

Vercel Connect is not configured

What it means

The connection's credentialSource is 'vercel_connect', meaning tokens are fetched from the Vercel Connect token service instead of stored secrets, but either the connection has no externalCredential record or the vercelConnect client itself was not initialized (e.g. missing service configuration). The gateway throws 503 because the credential source is temporarily unusable, not because the caller did anything wrong.

Solutions

1. Set the Vercel Connect environment configuration so the vercelConnect client initializes (check server startup logs for the missing env var).
2. Re-link the external credential on the connection (re-run the Vercel Connect install/link flow so connection.externalCredential is populated).
3. If Vercel Connect is not intended, switch the connection's credentialSource back to 'paperclip_vault' with stored credentials.
4. Guard with a pre-call check: connection.credentialSource === 'vercel_connect' && connection.externalCredential before invoking tools.

Example fix

// before
if (connection.credentialSource === 'vercel_connect' && !connection.externalCredential) { /* will 503 */ }
// after: check client + credential availability before dispatch
if (connection.credentialSource === 'vercel_connect') {
  if (!vercelConnect) throw new Error('Vercel Connect client not configured; set VERCEL_CONNECT_* env vars');
  if (!connection.externalCredential) throw new Error('Connection missing external credential; re-link Vercel Connect');
}

if (connection.credentialSource === 'vercel_connect') {
  if (!connection.externalCredential) throw new Error('Connection missing Vercel Connect external credential');
  if (!vercelConnect) throw new Error('Vercel Connect client not initialized; check service configuration');
}

function isVercelConnectReady(c: typeof toolConnections.$inferSelect): boolean {
  return c.credentialSource !== 'vercel_connect' || (c.externalCredential !== null && vercelConnect !== undefined);
}

try {
  const headers = await resolveCredentialHeaders(session, connection, grant);
} catch (e) {
  if (e instanceof ToolGatewayHttpError && e.code === 'vercel_connect_unavailable') {
    // 503: fall back to a vault-stored credential or surface config guidance
  }
  throw e;
}

When it happens

Trigger: Resolving credential headers via resolveCredentialHeadersUnrecorded for a connection with credentialSource === 'vercel_connect' when connection.externalCredential is null, or when the vercelConnect client is undefined because the server lacks Vercel Connect configuration (team token / API URL).

Common situations: A connection was switched to vercel_connect but the external credential binding was never saved; the deployment is missing the Vercel Connect env vars so the client boots as undefined; a database restore dropped the externalCredential blob while keeping credentialSource set.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• A trusted viewer build is required for public chat reports
• ACPX provider package manifest must be an explicit…
• ACPX provider package root must be an explicit normalized…
• ACPX runtime executable must be a bounded executable file
• agent_authorization_required

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/6c553ed251680e82. Report an issue: GitHub.

Appendix: source

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

          .where(
            and(
              eq(runIdentityContexts.id, session.identityContextId!),
              eq(runIdentityContexts.companyId, session.companyId),
            ),
          );
      throw error;
    }
  }

  async function resolveCredentialHeadersUnrecorded(
    session: ToolGatewaySession,
    connection: typeof toolConnections.$inferSelect,
    grant: typeof connectionGrants.$inferSelect,
    resolveOptions: { forceRefresh?: boolean } = {},
  ): Promise<Record<string, string>> {
    if (connection.credentialSource === "vercel_connect") {
      if (!connection.externalCredential || !vercelConnect) {
        throw new ToolGatewayHttpError(
          503,
          "Vercel Connect is not configured",
          "vercel_connect_unavailable",
          {
            connectionId: connection.id,
            grantId: grant.id,
          },
        );
      }
      const request = vercelTokenRequest({
        credential: connection.externalCredential,
        grant,
        connectionId: connection.id,
        companyId: connection.companyId,
      });
      try {
        const token = await vercelConnect.getToken(request, resolveOptions);
        if (

View on GitHub (pinned to 3f1d897a7c)