coleam00/Archon · error · Error

Container isolation is folder-project-only for now. Run --co

Error message

Container isolation is folder-project-only for now. Run --container against a registered folder project (or add --folder to register this directory as one). Repo projects use worktree isolation.

What it means

Container isolation (--container) is limited to folder-kind projects in v1. Repo-kind projects (and bare git repos or unregistered non-git directories) use worktree isolation instead, which is a silent downgrade of the requested isolation — so the CLI fails fast with this error rather than ignoring --container. The comment in source documents the intent: no surprising isolation downgrade.

Source

Thrown at packages/cli/src/commands/workflow.ts:2444

    console.log(`Resuming workflow run: ${resumable.id}`);
    console.log(`Working path: ${workingCwd}`);
    console.log('');

    // --resume adopts the prior run's worktree, so --base is half-applied here
    // exactly as it is on --branch reuse above: the cut-from is already fixed,
    // but flagBase still rides opts.baseOverride into $BASE_BRANCH.
    if (flagBase) {
      warnBaseOverrideOnReuse(workingCwd, flagBase);
    }
  }

  const isFolderCodebase = codebase?.kind === 'folder';

  // Container isolation is folder-project-only in v1. A repo-kind project (or a
  // bare git repo / unregistered non-git cwd) with --container fails fast rather
  // than silently running a worktree/in-place — no surprising isolation downgrade.
  if (options.container && !isFolderCodebase) {
    throw new Error(
      'Container isolation is folder-project-only for now. Run --container against a ' +
        'registered folder project (or add --folder to register this directory as one). ' +
        'Repo projects use worktree isolation.'
    );
  }

  // The codebase's stored default branch, used as the base-branch fallback when
  // repo config sets no worktree.baseBranch (reuse validation, worktree
  // creation, and $BASE_BRANCH resolution all derive from this one value).
  const codebaseDefaultBranch = codebase?.default_branch?.trim() || undefined;

  // Authoritative folder guards for an already-registered folder project run
  // WITHOUT the --folder flag (the flag-based guards above only fire when the
  // caller declared intent). Fail fast before any worktree work.
  assertNoWorktreeOptionsForFolder(isFolderCodebase, options);
  assertWorkflowNotWorktreePinnedForFolder(isFolderCodebase, pinnedEnabled, workflow.name);

  if (isFolderCodebase && codebase) {

View on GitHub (pinned to 0773b97458)

Solutions

Add --folder to register the current directory as a folder project, then use --container: `archon workflow run <flow> --folder --container`.
Run --container from a directory already registered as a folder project.
If the project is a git repo, drop --container and rely on worktree isolation, or restructure the project as a folder project if container isolation is essential.

Example fix

// before
cd ~/work/git-project && archon workflow run my-flow --container  # folder-project-only
// after
cd ~/work/folder-project && archon workflow run my-flow --folder --container

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'fs';
const isGitRepo = existsSync(join(cwd, '.git'));
if (wantContainer && isGitRepo) {
  throw new Error('--container requires a folder project; use worktree isolation for repo projects, or register with --folder.');
}

Type guard

function supportsContainer(c: { kind: string } | null | undefined): boolean {
  return c?.kind === 'folder';
}

Try / catch

try {
  await runWorkflow({ container: true });
} catch (error) {
  if ((error as Error).message.includes('folder-project-only')) {
    console.error('Either drop --container (repo projects use worktrees) or run with --folder from a folder project.');
  } else throw error;
}

Prevention

Use --container only inside registered folder projects.
For git repos, rely on worktree isolation by default.
Check the project kind with your codebase listing command before adding --container.

When it happens

Trigger: Running `archon workflow run <flow> --container` when the resolved codebase kind is not 'folder': a registered repo project, a bare git repo, or an unregistered non-git directory (codebase undefined or kind 'repo').

Common situations: Users assuming --container works everywhere and running it inside a normal git repo; forgetting to register the directory as a folder project with --folder; copy-pasting a container command from a folder-project example into a repo checkout.

Related errors

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