paperclipai/paperclip · error · Error

Fake setup session not found.

Error message

Fake setup session not found.

What it means

Thrown by the fake sandbox plugin's onEnvironmentCaptureTemplate() when no setup session is found in the in-memory setupSessions map for the given providerLeaseId (or providerLeaseId is undefined/null). The fake sandbox is a test double that simulates an interactive environment provider; capture requires a live setup session previously created via onEnvironmentStartInteractiveSetup().

Source

Thrown at packages/plugins/paperclip-plugin-fake-sandbox/src/plugin.ts:428

        status: "missing",
        connectionSummary: null,
        connectionPayload: null,
        metadata: {
          provider: "fake-plugin",
          found: false,
        },
      };
    }
    return presentSetupSession(state, { includeConnectionPayload: params.includeConnectionPayload === true });
  },

  async onEnvironmentCaptureTemplate(
    params: PluginEnvironmentCaptureTemplateParams,
  ): Promise<PluginEnvironmentCaptureTemplateResult> {
    const config = parseConfig(params.config);
    const state = params.providerLeaseId ? setupSessions.get(params.providerLeaseId) : undefined;
    if (!state) {
      throw new Error("Fake setup session not found.");
    }
    if (state.status === "cancelled" || state.status === "timed_out" || state.status === "failed") {
      throw new Error(`Fake setup session cannot be captured from status ${state.status}.`);
    }

    state.status = "capturing";
    const templateRef = buildTemplateRef(state.environmentId, state.sessionId);
    const template: FakeTemplateState = {
      templateRef,
      environmentId: state.environmentId,
      sessionId: state.sessionId,
      image: config.image,
      sourceTemplateRef: params.sourceTemplateRef ?? state.sourceTemplateRef,
      previousTemplateRef: params.previousTemplateRef ?? null,
      deleted: false,
    };
    templates.set(templateRef, template);
    state.status = "promoted";

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Ensure onEnvironmentStartInteractiveSetup() ran first and returned a providerLeaseId; pass that exact id to captureTemplate.
2. Re-open the setup session via onEnvironmentStartInteractiveSetup() (it is idempotent and reuses or recreates the session for the environmentId/sessionId pair).
3. In tests, reset the fake sandbox state between cases so lease ids from prior runs do not leak.

Example fix

// before
await plugin.onEnvironmentCaptureTemplate({ providerLeaseId: staleOrMissingId, ... });
// after
const session = await plugin.onEnvironmentStartInteractiveSetup({ environmentId, sessionId, ... });
await plugin.onEnvironmentCaptureTemplate({ providerLeaseId: session.providerLeaseId, ... });

// before capturing, ensure a session exists
const session = await plugin.onEnvironmentGetInteractiveSetup({ providerLeaseId });
if (session.status === "missing") {
  const started = await plugin.onEnvironmentStartInteractiveSetup({ environmentId, sessionId /* ... */ });
  // use started.providerLeaseId
}

function hasSetupSession<T extends { status: string }>(s: T | undefined): s is T & { status: Exclude<T["status"], "missing"> } {
  return !!s && (s as { status: string }).status !== "missing";
}

try {
  await plugin.onEnvironmentCaptureTemplate({ providerLeaseId, ... });
} catch (err) {
  if (err instanceof Error && err.message === "Fake setup session not found.") {
    // re-open setup then retry once
  } else throw err;
}

When it happens

Trigger: Calling captureTemplate with a providerLeaseId that was never started, or after the session was evicted by removeLease(). Calling captureTemplate without a providerLeaseId (the lookup is skipped and state is undefined). Calling capture after the session expired and was garbage-collected by the fake provider.

Common situations: Test harness calling capture before start. Using a stale lease id from a previous test run in a long-lived fake sandbox instance. Race between cancel/timeout cleanup and a capture attempt.

Related errors

• Fake setup session cannot be captured from status ${state.st
• Current directory is not inside a git repository.
• Paperclip sandbox proxy socket path is ${pathBytes} bytes, e
• Unable to create a Linux-safe Paperclip sandbox proxy socket
• Local process filesystem and network scopes are currently su

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/c7834e5ee91f0b71. Report an issue: GitHub.