coleam00/Archon · error · IsolationBlockedError

Isolation environment required but could not be created

Error message

Isolation environment required but could not be created

What it means

validateAndResolveIsolation throws IsolationBlockedError when the isolation mode (e.g. worktree) was required for a run but the isolation environment could not be created. Before throwing, the resolved result's userMessage has already been sent to the conversation, so this error is the internal signal that the run cannot proceed safely without isolation. It exists to prevent unisolated execution of work that demands isolation.

Solutions

Read result.reason / the userMessage already sent to the conversation to see why isolation provisioning failed.
Verify the codebase registration points at a valid git repository (kind is repo, not folder) and that `git worktree add` succeeds manually.
Check disk space and write permissions on the Archon workspace directory where worktrees are created.
If isolation is not actually required, dispatch without requesting isolation (isolation: 'none').

Example fix

// before: dispatching with required worktree isolation on a folder codebase
run({ codebaseId: 'docs-folder', isolation: 'worktree' })
// after: register the codebase as a git repo or drop the isolation requirement
run({ codebaseId: 'app-repo', isolation: 'worktree' })

Defensive patterns

Strategy: try-catch

Validate before calling

// before dispatch
codebase = await getCodebase(ctx.codebaseId);
if (codebase.kind !== 'repo') throw new Error('worktree isolation requires a git-repo codebase');

Try / catch

try {
  await dispatch(...);
} catch (e) {
  if (e instanceof IsolationBlockedError) {
    console.error('Isolation blocked:', e.reason); // surface e.reason to the operator
  } else throw e;
}

Prevention

Only request worktree isolation for codebases registered as git repos.
Ensure the workspace volume has free disk space and write permissions.
Smoke-test `git worktree add` on the host before enabling isolation.

When it happens

Trigger: Calling the orchestrator with isolation set to 'worktree' (or similar required mode) when createChildWorktreeResolver/isolation provisioning fails, e.g. the codebase is not a git repo, git worktree add fails, or the workspace is unwritable. The 'blocked' branch of the isolation switch produces it.

Common situations: Dispatching a workflow with per-child worktree isolation against a codebase whose kind is not a git repo, a detached/dirty git directory where worktree creation fails, disk-full or permission errors under the Archon workspace, or running outside a git clone.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/dd94661a907f13a3. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/src/orchestrator/orchestrator.ts:265

        );
      }
      return validateAndResolveIsolation(
        { ...conversation, isolation_env_id: null },
        codebase,
        platform,
        conversationId,
        hints,
        true,
        userId
      );
    }

    case 'none':
      return { status: 'none', cwd: result.cwd, env: null };

    case 'blocked':
      await platform.sendMessage(conversationId, result.userMessage);
      throw new IsolationBlockedError(
        'Isolation environment required but could not be created',
        result.reason
      );
  }
}

/**
 * Context for workflow routing - avoids passing many parameters
 */
export interface WorkflowRoutingContext {
  readonly platform: IPlatformAdapter;
  readonly conversationId: string;
  readonly cwd: string;
  readonly originalMessage: string;
  readonly conversationDbId: string;
  readonly codebaseId?: string;
  readonly availableWorkflows: readonly WorkflowDefinition[];
  /**

View on GitHub (pinned to 0773b97458)