Factory session ${session.sessionId} was retired during work

Error message

Factory session ${session.sessionId} was retired during workspace materialization

What it means

While a workspace is being materialized, the Factory session can concurrently be retired (user closed it, timeout, admin action). After registration completes, the code checks whether registration is still present; if the retirement path already removed it, creation aborts with this error because continuing would produce a workspace backed by a VM the retirement path may stop or destroy.

Source

Thrown at mastracode/factory/src/workspace.ts:682

    // sandbox: construction is eager while the VM start is lazy, so a session
    // retired before its first tool call still has a workspace (and possibly a
    // token injector) that must be torn down.
    const registered = await workspaceRegistry.register(
      session.sessionId,
      workspaceId,
      workspaceGeneration,
      async () => {
        githubTokenInjectors.delete(workspaceId);
        constructedWorkspaces.delete(workspaceId);
        // Retirement drops the memoized session sandbox so a later re-open
        // constructs (and the provider resolves) fresh instead of reusing an
        // instance whose VM the retirement path may stop or destroy.
        evictSessionSandbox(session.id);
        await mastra?.removeWorkspace?.(workspaceId);
      },
    );
    if (!registered) {
      throw new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
    }

    // Fully lazy: nothing provisions until the first real sandbox operation
    // (`ensureRunning()` inside the provider). A background warm-up at session
    // start was considered and dropped — it speculatively created a VM for
    // every session, including ones whose agent never touches the workspace.
    return workspace;
  };
}

View on GitHub (pinned to 75dd419e61)

Solutions

Retry the agent request — it will fail cleanly against the retired session or a new session will be created
Confirm the session is actually retired and start a new Factory session
If it fires while the session is still alive, check for a retirement race: look at logs for evictSessionSandbox around this error
Slow setups increase the race window — speed up setupCommand or move heavy work out of materialization

Defensive patterns

Strategy: retry

Validate before calling

// check session liveness before materializing
const state = await getSessionState(session.id);
if (state.status !== 'active') {
  throw new Error(`Session ${session.sessionId} is ${state.status}; start a new session before materializing workspaces`);
}

Try / catch

try {
  const factory = await createWorkspaceFactory(session);
} catch (e) {
  if (e instanceof Error && e.message.includes('was retired during workspace materialization')) {
    const fresh = await createSession(); // start a new session, then retry
    return createWorkspaceFactory(fresh);
  }
  throw e;
}

Prevention

Avoid retiring sessions while initial workspace setup is in flight (grace period)
Keep setupCommand fast so the materialization window is small
Detect retirement early (poll or webhook) and abort materialization proactively
Surface 'session closed' in the UI instead of retrying against a retired session

When it happens

Trigger: `createWorkspaceFactory` calls the registration step which returns null (`registered` is falsy) because `evictSessionSandbox`/retirement ran between session setup and workspace registration for `session.sessionId`.

Common situations: User closes/retires the session while the first workspace is still materializing; idle-timeout retirement racing with a slow clone/setup; admin force-retires a stuck session; retry logic re-entering after retirement.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/7d08ab9f03bec130. Report an issue: GitHub.