paperclipai/paperclip · error · Error

Prepare local sign-in before connecting.

Error message

Prepare local sign-in before connecting.

What it means

In `isolated` mode, connect() must reuse a prepared local sign-in session: the flow first prepares an attempt (getting a `sessionId`), then connects with `localSessionId`. Connecting with no prepared attempt would start a local sign-in outside the isolated session contract, so this guard throws.

Solutions

1. Await a successful preparation (non-null `attempt`/status ready) before enabling the Connect button.
2. If preparation failed, use the returned `retry()` to restart it instead of calling connect directly.
3. In non-isolated contexts, verify the `isolated` flag is intentional; it changes the required call order.

Example fix

// before
onClick={() => connect()}
// after
onClick={() => { if (isolated && !attempt) retry(); else connect(); }}

if (isolated && !attempt) { retry(); return; } await connect();

const isPrepared = (a: unknown): a is { sessionId: string } => !!a && typeof (a as any).sessionId === 'string';

try { await connect(); } catch (e) { if (/Prepare local sign-in/.test(e.message)) retry(); }

When it happens

Trigger: Calling `connect()` while `isolated` is true and `attempt` is null — i.e. skipping the prepare step or the prepare attempt failed/was cancelled before connect was clicked.

Common situations: User clicks Connect before the local sign-in preparation finished; preparation errored and UI still allowed connect; `retry()` bumped the generation and cleared the attempt, then connect was called.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Agent not found
• Attachment was removed
• capability_live_attempt_active_turn
• capability_live_attempt_not_running
• Capability live session already has an active turn

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/eb5dcb60f5f98f18. Report an issue: GitHub.

Appendix: source

Thrown at ui/src/components/ai-connections/useLocalAiLogin.ts:88

      cancelled = true;
      clearTimeout(timer);
      window.removeEventListener("focus", onFocus);
      document.removeEventListener("visibilitychange", onFocus);
      // Navigation is not cancellation. The server resumes this bounded attempt
      // when the user returns and reaps abandoned attempts after expiry. Deleting
      // here made copied CODEX_HOME commands point at nonexistent directories.
    };
  }, [companyId, active, isolated, target, generation]);
  return {
    isolated,
    command: attempt?.command,
    status,
    preparing: active && !status && !error,
    error,
    retry: () => { restartRequested.current = true; cancelCurrent(); setGeneration((value) => value + 1); },
    connect: (input = intent) => {
      if (!companyId) throw new Error("Choose a company before connecting.");
      if (isolated && !attempt) throw new Error("Prepare local sign-in before connecting.");
      return aiConnectionsApi.connectLocal(companyId, { ...input, ...(attempt ? { localSessionId: attempt.sessionId } : {}) });
    },
  };
}

View on GitHub (pinned to 3f1d897a7c)