paperclipai/paperclip · error

workspace_login_handoff_unavailable

workspace_login_handoff_unavailable

Error message

workspace_login_handoff_unavailable

What it means

issueWorkspaceLoginHandoff failed to issue a login handoff for the workspace (reason logged); the route maps the failure to a status via workspaceLoginHandoffFailureStatus, meaning direct workspace login is currently unavailable through this path.

Source

Thrown at server/src/routes/execution-workspaces.ts:218

      executionWorkspace: { id: workspace.id, cwd: workspace.cwd },
      actor: {
        userId: req.actor.userId ?? null,
        userEmail: req.actor.userEmail ?? null,
        source: req.actor.source ?? null,
      },
      next: requestedNext,
    });

    if (!result.ok) {
      logger.warn(
        {
          executionWorkspaceId: workspace.id,
          reason: result.failure.reason,
          detail: "detail" in result.failure ? result.failure.detail : null,
        },
        "workspace login handoff was not issued",
      );
      res.status(workspaceLoginHandoffFailureStatus(result.failure)).json({
        error: "workspace_login_handoff_unavailable",
        // The UI turns this into the labeled snapshot-local credential fallback
        // or a repair prompt, so the machine reason has to survive the boundary.
        reason: result.failure.reason,
        mode: "credentials",
        ...("detail" in result.failure ? { detail: result.failure.detail } : {}),
        ...("readiness" in result.failure ? { readiness: result.failure.readiness } : {}),
      });
      return;
    }

    await logActivity(db, {
      companyId: workspace.companyId,
      // Auditing issuance is a requirement of the handoff design: the nonce ties
      // this record to the guest's own accept/reject record. The ticket itself is
      // never recorded.
      action: "workspace_login_handoff_issued",
      entityType: "execution_workspace",

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Inspect the logged failure.reason/detail for the handoff blocker
2. Ensure the workspace runtime service is healthy and reachable
3. Retry the handoff after the workspace service recovers
4. Use the workspace's direct access path if available

When it happens

Trigger: Thrown at server/src/routes/execution-workspaces.ts:218 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-21). Data as JSON: /api/errors/0a138b1a90875cdc. Report an issue: GitHub.