{"record":{"id":"6823f696217106d6","repo":"paperclipai/paperclip","slug":"the-setup-token-login-session-could-not-start-6823f6","errorCode":null,"errorMessage":"The setup-token login session could not start.","messagePattern":"The setup-token login session could not start\\.","errorType":"exception","errorClass":"SetupTokenSessionError","httpStatus":503,"severity":"error","filePath":"server/src/services/setup-token-session.ts","lineNumber":956,"sourceCode":"      secretStored: false,\n      timer: null,\n      retentionTimer: null,\n      cleanupDone: false,\n      lock: Promise.resolve(),\n      reservation,\n    };\n\n    let process: SetupTokenLoginProcess;\n    try {\n      process = this.factory({\n        scope,\n        onPrompt: (prompt) => this.onPrompt(session, prompt),\n        onCredential: (token) => this.onCredential(session, token),\n        timeoutMs: this.ttlMs,\n        signal: abort.signal,\n      });\n    } catch {\n      // The factory could not start the process. Release the lease, drop the\n      // durable record, roll back the reservation, then return a fixed,\n      // non-secret error.\n      await this.releaseLeaseSafely(lease);\n      await this.store\n        .remove({\n          sessionId,\n          companyId: scope.companyId,\n          ownerUserId: scope.ownerUserId,\n          adapterType: scope.adapterType,\n        })\n        .catch(() => {});\n      this.releaseReservation(reservation);\n      throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);\n    }\n\n    session.process = process;\n    session.timer = setTimeout(() => {\n      void this.expireInternal(sessionId);","sourceCodeStart":938,"sourceCodeEnd":974,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/server/src/services/setup-token-session.ts#L938-L974","documentation":"Thrown by SetupTokenSessionService.start when the login process factory itself throws synchronously (server/src/services/setup-token-session.ts:919, SETUP_TOKEN_START_FAILED, HTTP 503). At that point the service has already acquired a lease, written a durable 'starting' record, and reserved capacity; the catch block releases the lease, removes the store record, and rolls back the reservation before surfacing the fixed, non-secret error. The underlying factory failure is deliberately not exposed.","triggerScenarios":"Calling start(scope) when this.factory(...) throws — the adapter-specific process that drives the setup-token login (e.g. spawning the adapter's login binary/CLI) failed to start: missing executable, bad adapter configuration, unsupported adapter type on the host, or immediate spawn errors like ENOENT.","commonSituations":"Adapter login binary not installed on the server (PATH/ENOENT); adapterType with no registered factory; factory misconfigured after a deploy; platform where the login helper cannot run (permissions, missing runtime).","solutions":["Check server logs for the swallowed factory error thrown just before the 503 — the response intentionally hides it.","Verify the adapter's login process prerequisites on the host: binary installed, executable bit set, correct PATH and config.","Confirm scope.adapterType is one the factory supports in this deployment.","Retry start once the prerequisite is fixed; capacity and lease state were rolled back, so the retry starts clean."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const factoryOk = await adapterLoginFactorySelfCheck(scope.adapterType); // e.g. verify binary exists and is executable\nif (!factoryOk) throw new Error(\"Adapter login process prerequisites missing; fix before starting a session.\");","typeGuard":null,"tryCatchPattern":"try { return await svc.start(scope); } catch (err) { if (err instanceof SetupTokenSessionError && err.status === 503 && err.code === SETUP_TOKEN_START_FAILED) { await installAdapterLoginPrereqs(scope.adapterType); return await svc.start(scope); /* state was rolled back; retry is clean */ } throw err; }","preventionTips":["Verify adapter login binaries are installed and on PATH on every server host before enabling setup-token flows.","Log the underlying factory error server-side — the 503 intentionally hides it from callers.","Smoke-test start() for each adapterType after deploys that touch adapter factories."],"tags":["setup-token","login-session","process-spawn","http-503","rollback"],"backgroundTag":"process-spawn-failed","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-08-21T17:58:32.592Z","contentChangedAt":"2026-08-21T17:58:32.592Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}