coleam00/Archon · error

artifacts.path_escape_blocked

artifacts.path_escape_blocked

Error message

Invalid artifact path

What it means

The artifacts listing endpoint resolved a run's artifact directory, but isInsideArchonHome(artifactDir) returned false — the path points outside the configured Archon home. This is a path-escape guard returning 400 to prevent serving files from arbitrary filesystem locations.

Source

Thrown at packages/server/src/routes/api.ts:4698

          { err: error, runId, codebaseId: run.codebase_id },
          'artifacts.codebase_lookup_failed'
        );
        return apiError(c, 500, 'Failed to look up codebase');
      }
    }
    // An empty 200 here is indistinguishable from "the run produced nothing",
    // so an unresolvable output location is an explicit 404 (Fail Fast).
    const artifactDir = resolveRunArtifactDir(run, codebase, runId);
    if (!artifactDir) {
      getLog().warn({ runId, codebaseId: run.codebase_id }, 'artifacts.output_location_unresolved');
      return apiError(
        c,
        404,
        'Artifacts not available: could not resolve this run’s output location'
      );
    }
    if (!isInsideArchonHome(artifactDir)) {
      getLog().warn(
        { runId, artifactDir, archonHome: getArchonHome() },
        'artifacts.path_escape_blocked'
      );
      return apiError(c, 400, 'Invalid artifact path');
    }

    interface FileEntry {
      path: string;
      size: number;
      modifiedAt: string;
    }
    const files: FileEntry[] = [];

    async function walk(dir: string, rel: string): Promise<void> {
      let entries: { name: string; isDirectory: () => boolean; isFile: () => boolean }[];
      try {
        entries = await readdir(dir, { withFileTypes: true });
      } catch (err) {

View on GitHub (pinned to 0773b97458)

Solutions

1. Point ARCHON_HOME back to the location that contains the run's artifacts, or migrate the artifact directories under the current home
2. Inspect the warn log's artifactDir vs archonHome values to see exactly where the mismatch is
3. Re-run the workflow under the current configuration so artifacts land inside the home
4. Do not bypass the guard; fix the path configuration instead

Example fix

null

import { isInsideArchonHome } from '@archon/paths';
// pre-check client-side of deployment config:
const dir = resolveRunArtifactDir(run, codebase, runId);
if (dir && !isInsideArchonHome(dir)) throw new Error(`artifact dir ${dir} escapes ARCHON_HOME ${getArchonHome()}`);

function artifactDirIsSafe(dir: string | null, isInside: (p: string) => boolean): dir is string {
  return typeof dir === 'string' && isInside(dir);
}

null

When it happens

Trigger: GET run artifacts where resolveRunArtifactDir returns a directory outside getArchonHome() — typically because ARCHON_HOME changed between runs or the stored run/codebase path references a foreign location.

Common situations: Moving or renaming the Archon home directory while old runs persist; restored database referencing paths from another machine; misconfigured ARCHON_HOME env var.

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

• Checksum mismatch: expected ${expectedHash}, got ${actualHas
• Untrusted source URL for '${slug}': ${entry.sourceUrl} Only
• Detached run control path is not a directory: ${directory}
• Detached run control directory is owned by another user: ${d
• Detached run control directory must have mode 0700: ${direct

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