coleam00/Archon · error

.archon/config.yaml worktree.path must stay within the repo

Error message

.archon/config.yaml worktree.path must stay within the repo (got: ${trimmed}). Remove any `..` segments.

What it means

WorktreeProvider validates the optional `worktree.path` override in `.archon/config.yaml` before using it as the worktree base directory. A value containing a `..` segment would place worktrees outside the repository, which the per-repo override is not allowed to do. This fail-fast check runs during path resolution in resolveRepoLocalOverride.

Source

Thrown at packages/isolation/src/providers/worktree.ts:127

  if (!trimmed) return undefined;

  if (isAbsolute(trimmed)) {
    throw new Error(
      `.archon/config.yaml worktree.path must be relative to the repo root (got absolute: ${trimmed}). ` +
        'For an absolute location, set ~/.archon/config.yaml paths.worktrees instead.'
    );
  }

  const normalized = normalizePath(trimmed);
  // A plain `..` or anything that starts with `../` or contains `/../` escapes the repo.
  if (
    normalized === '..' ||
    normalized.startsWith('../') ||
    normalized.startsWith('..\\') ||
    normalized.includes('/../') ||
    normalized.includes('\\..\\')
  ) {
    throw new Error(
      `.archon/config.yaml worktree.path must stay within the repo (got: ${trimmed}). ` +
        'Remove any `..` segments.'
    );
  }

  // Double-check via resolved absolute paths — catches edge cases like a path that
  // normalizes clean but still escapes when joined (e.g. leading `./../` on some platforms).
  // Uses `path.sep` so the "is inside repoRoot" check works on Windows (\\) as well as POSIX (/).
  const resolved = resolve(repoRoot, normalized);
  const repoRootResolved = resolve(repoRoot);
  if (resolved !== repoRootResolved && !resolved.startsWith(repoRootResolved + sep)) {
    throw new Error(
      `.archon/config.yaml worktree.path resolves outside the repo root (got: ${trimmed} → ${resolved}).`
    );
  }

  return normalized;
}

View on GitHub (pinned to 0773b97458)

Solutions

1. Remove all `..` segments from `worktree.path` and use a path relative to and inside the repo root, e.g. `.worktrees`
2. If you need worktrees outside the repo, set an absolute location in the global `~/.archon/config.yaml` under `paths.worktrees` instead
3. Delete the `worktree.path` key entirely to fall back to default worktree path resolution

Example fix

# before (.archon/config.yaml)
worktree:
  path: ../shared-worktrees
# after
worktree:
  path: .worktrees

import { isAbsolute, resolve, sep } from 'node:path';
export function validateWorktreePath(rawPath: string | undefined, repoRoot: string): void {
  const t = rawPath?.trim();
  if (!t) return;
  if (isAbsolute(t)) throw new Error(`worktree.path must be relative: ${t}`);
  const normalized = t.replace(/\\/g, '/');
  if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
    throw new Error(`worktree.path must stay within the repo: ${t}`);
  }
  const resolved = resolve(repoRoot, t);
  if (!resolved.startsWith(resolve(repoRoot) + sep)) {
    throw new Error(`worktree.path resolves outside repo: ${t} -> ${resolved}`);
  }
}

When it happens

Trigger: Setting `worktree.path` in `.archon/config.yaml` to a value like `../worktrees`, `..`, `foo/../..`, or any path whose normalized form starts with or contains a `..` segment, then triggering worktree creation (WorktreeProvider.create / getWorktreePath).

Common situations: Developers trying to share one worktree directory across several repos by pointing the path at a sibling folder; copying a global absolute-style location into the per-repo config; typos like `./../worktrees`.

Related errors

• .archon/config.yaml worktree.path must be relative to the re
• .archon/config.yaml worktree.path resolves outside the repo
• Failed to load config: ${err.message}
• --resume and --config are mutually exclusive. A resumed run
• Cannot create worktree: database lookup failed. Error: ${res

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