{"record":{"id":"6c553ed251680e82","repo":"paperclipai/paperclip","slug":"vercel-connect-unavailable","errorCode":"vercel_connect_unavailable","errorMessage":"Vercel Connect is not configured","messagePattern":"Vercel Connect is not configured","errorType":"http","errorClass":"ToolGatewayHttpError","httpStatus":503,"severity":"error","filePath":"server/src/services/tool-gateway.ts","lineNumber":3867,"sourceCode":"          .where(\n            and(\n              eq(runIdentityContexts.id, session.identityContextId!),\n              eq(runIdentityContexts.companyId, session.companyId),\n            ),\n          );\n      throw error;\n    }\n  }\n\n  async function resolveCredentialHeadersUnrecorded(\n    session: ToolGatewaySession,\n    connection: typeof toolConnections.$inferSelect,\n    grant: typeof connectionGrants.$inferSelect,\n    resolveOptions: { forceRefresh?: boolean } = {},\n  ): Promise<Record<string, string>> {\n    if (connection.credentialSource === \"vercel_connect\") {\n      if (!connection.externalCredential || !vercelConnect) {\n        throw new ToolGatewayHttpError(\n          503,\n          \"Vercel Connect is not configured\",\n          \"vercel_connect_unavailable\",\n          {\n            connectionId: connection.id,\n            grantId: grant.id,\n          },\n        );\n      }\n      const request = vercelTokenRequest({\n        credential: connection.externalCredential,\n        grant,\n        connectionId: connection.id,\n        companyId: connection.companyId,\n      });\n      try {\n        const token = await vercelConnect.getToken(request, resolveOptions);\n        if (","sourceCodeStart":3849,"sourceCodeEnd":3885,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/tool-gateway.ts#L3849-L3885","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set the Vercel Connect environment configuration so the vercelConnect client initializes (check server startup logs for the missing env var).","Re-link the external credential on the connection (re-run the Vercel Connect install/link flow so connection.externalCredential is populated).","If Vercel Connect is not intended, switch the connection's credentialSource back to 'paperclip_vault' with stored credentials.","Guard with a pre-call check: connection.credentialSource === 'vercel_connect' && connection.externalCredential before invoking tools."],"exampleFix":"// before\nif (connection.credentialSource === 'vercel_connect' && !connection.externalCredential) { /* will 503 */ }\n// after: check client + credential availability before dispatch\nif (connection.credentialSource === 'vercel_connect') {\n  if (!vercelConnect) throw new Error('Vercel Connect client not configured; set VERCEL_CONNECT_* env vars');\n  if (!connection.externalCredential) throw new Error('Connection missing external credential; re-link Vercel Connect');\n}","handlingStrategy":"fallback","validationCode":"if (connection.credentialSource === 'vercel_connect') {\n  if (!connection.externalCredential) throw new Error('Connection missing Vercel Connect external credential');\n  if (!vercelConnect) throw new Error('Vercel Connect client not initialized; check service configuration');\n}","typeGuard":"function isVercelConnectReady(c: typeof toolConnections.$inferSelect): boolean {\n  return c.credentialSource !== 'vercel_connect' || (c.externalCredential !== null && vercelConnect !== undefined);\n}","tryCatchPattern":"try {\n  const headers = await resolveCredentialHeaders(session, connection, grant);\n} catch (e) {\n  if (e instanceof ToolGatewayHttpError && e.code === 'vercel_connect_unavailable') {\n    // 503: fall back to a vault-stored credential or surface config guidance\n  }\n  throw e;\n}","preventionTips":["Validate Vercel Connect env configuration at server startup and fail fast if credentialSource rows exist without the client.","Treat switching a connection to credentialSource 'vercel_connect' without an externalCredential as an invalid state at write time.","Add a health check that flags vercel_connect connections missing externalCredential."],"tags":["configuration","vercel-connect","service-unavailable","http-503"],"backgroundTag":"missing-required-config","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}