paperclipai/paperclip · error

SETUP_TOKEN_PTY_OPEN_FAILED

SETUP_TOKEN_PTY_OPEN_FAILED

Error message

SETUP_TOKEN_PTY_OPEN_FAILED

What it means

The worker RPC to open the setup-token PTY failed (send error, rejection, or timeout), or the reply was malformed with no bindable worker session id. The route is terminalized once and this sentinel is raised to fail closed.

Source

Thrown at server/src/services/plugin-worker-manager.ts:1437

          environmentId: input.environmentId,
          providerLeaseId: input.providerLeaseId,
          command: input.command,
        },
        setupTokenPtyOpenTimeoutMs,
      );
    } catch (err) {
      // A send failure, an RPC rejection, or an open timeout. Terminalize the
      // route exactly once and fail closed.
      await terminalizeSetupTokenPtyRoute(route);
      throw err instanceof Error ? err : new Error(SETUP_TOKEN_PTY_OPEN_FAILED);
    }

    const workerSessionId = readBindableWorkerSessionId(route, openResult);
    if (!workerSessionId) {
      // A malformed reply, or a route that already left `opening`. A late or a
      // duplicate reply never binds, revives, or reopens a route.
      await terminalizeSetupTokenPtyRoute(route);
      throw new Error(SETUP_TOKEN_PTY_OPEN_FAILED);
    }
    // Bind the worker session identifier one time and move the route to `open`.
    route.workerSessionId = workerSessionId;
    route.state = "open";

    return {
      onData(listener: (chunk: string) => void): void {
        route.listener = listener;
        if (route.buffered.length > 0) {
          const pending = route.buffered;
          route.buffered = [];
          for (const chunk of pending) listener(chunk);
        }
      },
      write(data: string): void {
        const sid = route.workerSessionId;
        if (route.state !== "open" || !sid) return;
        void callInternal(

View on GitHub (pinned to a7e689b3c3)

Solutions

1. The PTY failed to open. Check server logs for the underlying spawn error (command not found, permissions) and retry.

When it happens

Trigger: Thrown at server/src/services/plugin-worker-manager.ts:1229 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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