What causes "Path must be within ${workspaceRoot} directory" in coleam00/Archon?

Pass a path relative to the workspace root (or within it) instead of an absolute outside path.

Path must be within ${workspaceRoot} directory

Error message

Path must be within ${workspaceRoot} directory

What it means

validateAndResolvePath resolves a target path against a base (defaults to the Archon workspace root) and throws if the resolved path escapes that root. It is the central path-traversal guard ensuring all file operations stay inside the workspace. The message names the workspace root that was violated.

Source

Thrown at packages/core/src/utils/path-validation.ts:42

  return resolvedTarget === workspaceRoot || resolvedTarget.startsWith(workspaceRoot + sep);
}

/**
 * Validates a path and returns the resolved absolute path if valid.
 * Throws an error if the path escapes the workspace.
 *
 * @param targetPath - The path to validate
 * @param basePath - Optional base path to resolve relative paths against
 * @returns The resolved absolute path
 * @throws Error if path is outside workspace
 */
export function validateAndResolvePath(targetPath: string, basePath?: string): string {
  const workspaceRoot = getWorkspaceRoot();
  const effectiveBase = basePath ?? workspaceRoot;
  const resolvedPath = resolve(effectiveBase, targetPath);

  if (!isPathWithinWorkspace(resolvedPath)) {
    throw new Error(`Path must be within ${workspaceRoot} directory`);
  }

  return resolvedPath;
}

View on GitHub (pinned to 0773b97458)

Solutions

Pass a path relative to the workspace root (or within it) instead of an absolute outside path.
If you intend to operate on an outside directory, register it as a codebase or use the appropriate API rather than raw path access.
Supply a basePath that already sits inside the workspace so the resolution stays within it.
Check for symlinks in the workspace that resolve outside the root and remove/re-point them.

Example fix

// before
validateAndResolvePath('/etc/hosts');
// after
validateAndResolvePath('runs/123/artifacts/output.json');

Defensive patterns

Strategy: validation

Validate before calling

import { isAbsolute, resolve } from 'node:path';
function assertWorkspaceRelative(p: string) {
  if (isAbsolute(p) || p.split(/[\\/]/).includes('..')) {
    throw new Error(`path must be workspace-relative: ${p}`);
  }
}
assertWorkspaceRelative(userPath); // then call validateAndResolvePath(userPath)

Type guard

function isWithin(root: string, target: string): boolean {
  const rel = relative(root, target);
  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
}

Try / catch

try {
  const p = validateAndResolvePath(input);
} catch (e) {
  if (e.message.includes('Path must be within')) {
    console.error('Reject the input path; it escapes the workspace root');
  } else throw e;
}

Prevention

Treat all user-supplied paths as untrusted; pass them through validateAndResolvePath first.
Use workspace-relative paths in workflow inputs and artifacts.
Audit for symlinks in the workspace that point outside the root.

When it happens

Trigger: Calling validateAndResolvePath with a path containing '..' or an absolute path outside the workspace, or passing a basePath whose resolution combined with targetPath lands outside the workspace root when isPathWithinWorkspace is checked.

Common situations: User-supplied file paths in workflow inputs reaching file APIs; symlinks or '..' segments in artifact paths; passing an absolute path from outside the Archon workspace (e.g. /etc/passwd or a project dir elsewhere on disk).

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

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