paperclipai/paperclip · error · SetupTokenSessionError

The setup-token login session could not start.

Error message

The setup-token login session could not start.

What it means

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.

Source

Thrown at server/src/services/setup-token-session.ts:956

      secretStored: false,
      timer: null,
      retentionTimer: null,
      cleanupDone: false,
      lock: Promise.resolve(),
      reservation,
    };

    let process: SetupTokenLoginProcess;
    try {
      process = this.factory({
        scope,
        onPrompt: (prompt) => this.onPrompt(session, prompt),
        onCredential: (token) => this.onCredential(session, token),
        timeoutMs: this.ttlMs,
        signal: abort.signal,
      });
    } catch {
      // The factory could not start the process. Release the lease, drop the
      // durable record, roll back the reservation, then return a fixed,
      // non-secret error.
      await this.releaseLeaseSafely(lease);
      await this.store
        .remove({
          sessionId,
          companyId: scope.companyId,
          ownerUserId: scope.ownerUserId,
          adapterType: scope.adapterType,
        })
        .catch(() => {});
      this.releaseReservation(reservation);
      throw new SetupTokenSessionError(503, SETUP_TOKEN_START_FAILED);
    }

    session.process = process;
    session.timer = setTimeout(() => {
      void this.expireInternal(sessionId);

View on GitHub (pinned to 01ad858492)

Solutions

1. Check server logs for the swallowed factory error thrown just before the 503 — the response intentionally hides it.
2. Verify the adapter's login process prerequisites on the host: binary installed, executable bit set, correct PATH and config.
3. Confirm scope.adapterType is one the factory supports in this deployment.
4. Retry start once the prerequisite is fixed; capacity and lease state were rolled back, so the retry starts clean.

const factoryOk = await adapterLoginFactorySelfCheck(scope.adapterType); // e.g. verify binary exists and is executable
if (!factoryOk) throw new Error("Adapter login process prerequisites missing; fix before starting a session.");

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; }

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Too many active setup-token login sessions.
• Plugin is not ready (current status: ${plugin.status})
• Plugin worker is not running
• managed_profile_unavailable
• agentcore_profile_unavailable

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-21). Data as JSON: /api/errors/6823f696217106d6. Report an issue: GitHub.