coleam00/Archon · error

Failed to load config: ${err.message}

Error message

Failed to load config: ${err.message}

What it means

WorktreeProvider.create loads `.archon/config.yaml` exactly once via the injected RepoConfigLoader. If the loader throws (unreadable file, YAML parse error, schema violation), the error is logged as `repo_config_load_failed` and rethrown wrapped as `Failed to load config: <original message>`. Archon fails loudly here rather than silently ignoring a malformed config.

Source

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

  constructor(private loadConfig: RepoConfigLoader = () => Promise.resolve(null)) {}

  /**
   * Create an isolated environment using git worktrees.
   *
   * Config is loaded exactly once here and threaded through the rest of the
   * `create()` call. A malformed `.archon/config.yaml` fails loudly at this
   * boundary rather than being swallowed — see CLAUDE.md "Fail Fast + Explicit
   * Errors". Downstream helpers assume they receive either a valid config
   * object or `null`, never a second chance to reload.
   */
  async create(request: IsolationRequest): Promise<IsolatedEnvironment> {
    let repoConfig: WorktreeCreateConfig | null;
    try {
      repoConfig = await this.loadConfig(request.canonicalRepoPath);
    } catch (error) {
      const err = error as Error;
      getLog().error({ err, repoPath: request.canonicalRepoPath }, 'repo_config_load_failed');
      throw new Error(`Failed to load config: ${err.message}`);
    }

    const branchName = toBranchName(this.generateBranchName(request));
    const worktreePath = this.getWorktreePath(request, branchName, repoConfig);
    // envId is, by contract, the worktree filesystem path (see `destroy()` docstring).
    // Assign directly from the resolved path to keep the invariant in sync with
    // the actual directory created below — computing it via a separate helper would
    // risk divergence if resolution rules change.
    const envId = worktreePath;

    // Check for existing worktree (adoption)
    const existing = await this.findExisting(request, branchName, worktreePath);
    if (existing) {
      return existing;
    }

    // Create new worktree (re-uses the already-loaded repoConfig — no double load).
    const { warnings } = await this.createWorktree(request, worktreePath, branchName, repoConfig);

View on GitHub (pinned to 0773b97458)

Solutions

1. Read the inner `err.message` after 'Failed to load config:' — it names the actual YAML/schema problem
2. Validate the YAML with a linter or parser (e.g. `yamllint`) and fix syntax/indentation
3. Check that `.archon/config.yaml` matches the expected WorktreeCreateConfig schema (correct keys and types)
4. Verify file read permissions on `.archon/config.yaml` for the user running Archon

Example fix

# before (invalid YAML)
worktree:
  baseBranch: main
   copyFiles: [.env]
# after
worktree:
  baseBranch: main
  copyFiles:
    - .env

import { readFileSync } from 'node:fs';
import { parse } from 'yaml';
export function assertConfigParses(path = '.archon/config.yaml'): void {
  const raw = readFileSync(path, 'utf8');
  const cfg = parse(raw); // throws with a line/column on bad YAML
  if (cfg?.worktree != null && typeof cfg.worktree !== 'object') {
    throw new Error('worktree section must be a mapping');
  }
}

function isWorktreeConfig(v: unknown): v is { baseBranch?: string; remote?: string; copyFiles?: string[] } {
  if (v == null || typeof v !== 'object') return false;
  const w = v as Record<string, unknown>;
  return (w.baseBranch === undefined || typeof w.baseBranch === 'string') &&
         (w.remote === undefined || typeof w.remote === 'string') &&
         (w.copyFiles === undefined || (Array.isArray(w.copyFiles) && w.copyFiles.every(f => typeof f === 'string')));
}

try {
  await provider.create(request);
} catch (e) {
  const msg = (e as Error).message;
  if (msg.startsWith('Failed to load config: ')) {
    console.error('Fix .archon/config.yaml:', msg.slice('Failed to load config: '.length));
    throw e;
  }
  throw e;
}

When it happens

Trigger: Calling WorktreeProvider.create(request) where the injected loadConfig for request.canonicalRepoPath throws — typically because `.archon/config.yaml` is unparseable YAML, fails schema validation, or the file cannot be read.

Common situations: Hand-edited YAML with indentation/tab errors, wrong types (e.g. `worktree.copyFiles` as a string instead of a list), a partially written config file, or permission problems on `.archon/config.yaml`.

Related errors

• Invalid run config at 'document': expected an object
• Invalid run config at 'docs': expected an object
• Invalid YAML in run config '${path}': ${(error as Error).mes
• .archon/config.yaml worktree.path must stay within the repo
• Alias name '${name}' must start with '@' (e.g. '@${name}').

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