.archon/config.yaml worktree.path must be relative to the re

Error message

.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.

What it means

resolveRepoLocalOverride reads worktree.path from .archon/config.yaml and requires it to be relative to the repo root. An absolute path there is rejected with guidance to use ~/.archon/config.yaml paths.worktrees for absolute locations, keeping repo-local config portable.

Source

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

 *
 * Rules (Fail Fast — malformed values throw; empty/whitespace values are ignored):
 * - `undefined` / empty-after-trim → `undefined` (no override; default resolution applies)
 * - Absolute path                  → throw (users must configure globally, not per-repo)
 * - Contains `..` segment          → throw (escapes repo root)
 * - Resolved path escapes repoRoot → throw (covers symlink / nested `../` edge cases)
 *
 * The path is returned trimmed. The caller composes it via `join(repoRoot, result)`.
 */
function resolveRepoLocalOverride(
  rawPath: string | undefined,
  repoRoot: string
): string | undefined {
  if (rawPath === undefined) return undefined;
  const trimmed = rawPath.trim();
  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.'
    );

View on GitHub (pinned to 0773b97458)

Solutions

Edit .archon/config.yaml to a path relative to the repo root, e.g. worktree.path: ../archon-worktrees
If an absolute location is genuinely required, set paths.worktrees in ~/.archon/config.yaml instead
Re-run the command after fixing the config

Example fix

# before (.archon/config.yaml)
worktree:
  path: /home/alice/worktrees/myrepo
# after (.archon/config.yaml)
worktree:
  path: ../worktrees/myrepo

Defensive patterns

Strategy: validation

Validate before calling

import { isAbsolute } from 'node:path';
const rawPath = config.worktree?.path;
if (rawPath !== undefined && isAbsolute(rawPath.trim())) {
  throw new Error('worktree.path must be relative in .archon/config.yaml');
}

Try / catch

try {
  const o = resolveRepoLocalOverride(cfg);
} catch (err) {
  if (String(err).includes('worktree.path must be relative')) {
    // fix the config, or move the absolute location to ~/.archon/config.yaml paths.worktrees
  }
  throw err;
}

Prevention

Keep repo-local config paths relative so they are portable
Put machine-specific absolute paths in ~/.archon/config.yaml
Validate .archon/config.yaml paths at startup or in CI

When it happens

Trigger: Setting worktree.path to an absolute path (leading '/' or 'C:\' etc.) in .archon/config.yaml and then resolving the override via override().

Common situations: Copying an absolute path from a teammate's machine into the shared repo config; pasting an absolute output from a previous tool; assuming repo config accepts absolute destinations like global config does.

Related errors

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