{"record":{"id":"fc77ed773e21d90f","repo":"coleam00/Archon","slug":"archon-config-yaml-worktree-path-must-be-relative","errorCode":null,"errorMessage":".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.","messagePattern":"\\.archon/config\\.yaml worktree\\.path must be relative to the repo root \\(got absolute: (.+?)\\)\\. For an absolute location, set ~/\\.archon/config\\.yaml paths\\.worktrees instead\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/isolation/src/providers/worktree.ts","lineNumber":112,"sourceCode":" *\n * Rules (Fail Fast — malformed values throw; empty/whitespace values are ignored):\n * - `undefined` / empty-after-trim → `undefined` (no override; default resolution applies)\n * - Absolute path                  → throw (users must configure globally, not per-repo)\n * - Contains `..` segment          → throw (escapes repo root)\n * - Resolved path escapes repoRoot → throw (covers symlink / nested `../` edge cases)\n *\n * The path is returned trimmed. The caller composes it via `join(repoRoot, result)`.\n */\nfunction resolveRepoLocalOverride(\n  rawPath: string | undefined,\n  repoRoot: string\n): string | undefined {\n  if (rawPath === undefined) return undefined;\n  const trimmed = rawPath.trim();\n  if (!trimmed) return undefined;\n\n  if (isAbsolute(trimmed)) {\n    throw new Error(\n      `.archon/config.yaml worktree.path must be relative to the repo root (got absolute: ${trimmed}). ` +\n        'For an absolute location, set ~/.archon/config.yaml paths.worktrees instead.'\n    );\n  }\n\n  const normalized = normalizePath(trimmed);\n  // A plain `..` or anything that starts with `../` or contains `/../` escapes the repo.\n  if (\n    normalized === '..' ||\n    normalized.startsWith('../') ||\n    normalized.startsWith('..\\\\') ||\n    normalized.includes('/../') ||\n    normalized.includes('\\\\..\\\\')\n  ) {\n    throw new Error(\n      `.archon/config.yaml worktree.path must stay within the repo (got: ${trimmed}). ` +\n        'Remove any `..` segments.'\n    );","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/isolation/src/providers/worktree.ts#L94-L130","documentation":"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.","triggerScenarios":"Setting worktree.path to an absolute path (leading '/' or 'C:\\' etc.) in .archon/config.yaml and then resolving the override via override().","commonSituations":"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.","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"],"exampleFix":"# before (.archon/config.yaml)\nworktree:\n  path: /home/alice/worktrees/myrepo\n# after (.archon/config.yaml)\nworktree:\n  path: ../worktrees/myrepo","handlingStrategy":"validation","validationCode":"import { isAbsolute } from 'node:path';\nconst rawPath = config.worktree?.path;\nif (rawPath !== undefined && isAbsolute(rawPath.trim())) {\n  throw new Error('worktree.path must be relative in .archon/config.yaml');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const o = resolveRepoLocalOverride(cfg);\n} catch (err) {\n  if (String(err).includes('worktree.path must be relative')) {\n    // fix the config, or move the absolute location to ~/.archon/config.yaml paths.worktrees\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["config","validation","worktree"],"backgroundTag":"config-path-must-be-relative","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}