coleam00/Archon · error · Error

Error loading workflows: ${err.message} Hint: Check permissi

Error message

Error loading workflows: ${err.message}
Hint: Check permissions on .archon/workflows/ directory.

What it means

loadWorkflows() wraps discoverWorkflowsWithConfig (which also unconditionally scans ~/.archon/workflows/) so any failure during workflow discovery/load becomes a uniform 'Error loading workflows' message with the original error text and a permissions hint. It indicates the CLI could not enumerate or read workflow files from the discovery directories.

Source

Thrown at packages/cli/src/commands/workflow.ts:1042

  }
}

/**
 * Load workflows from the DISCOVERY root with standardized error handling.
 *
 * The root passed here owns both the workflow files and the `defaults:` /
 * `commands.folder` settings that govern how they are discovered — a workflow's own
 * checkout decides which command folder its command nodes name. What the run then DOES
 * is governed separately by the target's config, loaded inside `executeWorkflow`.
 */
async function loadWorkflows(cwd: string): Promise<WorkflowLoadResult> {
  try {
    // Home-scoped workflows at ~/.archon/workflows/ are discovered automatically —
    // no option needed since the discovery helper reads them unconditionally.
    return await discoverWorkflowsWithConfig(cwd, loadConfig);
  } catch (error) {
    const err = error as Error;
    throw new Error(
      `Error loading workflows: ${err.message}\nHint: Check permissions on .archon/workflows/ directory.`
    );
  }
}

/**
 * Print a workflow's parse warnings (keys the engine silently drops) to stderr.
 *
 * stderr rather than stdout so `--json` callers keep a parseable payload while
 * still being told; `console.warn` rather than the logger because `--json` sets
 * the log level to silent, which is exactly the case this has to survive.
 */
export function emitParseWarnings(
  parseWarnings: readonly string[] | undefined,
  workflowName: string
): void {
  if (!parseWarnings || parseWarnings.length === 0) return;
  console.warn(`Warning: '${workflowName}' declares keys the engine ignores:`);

View on GitHub (pinned to 0773b97458)

Solutions

Check permissions on .archon/workflows/ and ~/.archon/workflows/ (`ls -la`) and ensure the running user can read them.
Read the embedded err.message — it names the specific file or directory that failed.
Fix ownership (`sudo chown -R $USER .archon/workflows`) if files were created by another user.
Remove or fix the offending workflow YAML file flagged in the message.
Verify HOME is set correctly if home-scoped discovery is failing.

Example fix

// before: root-owned workflow dir
$ ls -la .archon/workflows
drwx------ root root
$ archon workflow run foo
Error loading workflows: EACCES: permission denied ...
// after
$ sudo chown -R $USER .archon/workflows && chmod -R u+rwX .archon/workflows

Defensive patterns

Strategy: validation

Validate before calling

import { accessSync, constants, readdirSync } from 'fs';
for (const dir of ['.archon/workflows', `${process.env.HOME}/.archon/workflows`]) {
  try {
    accessSync(dir, constants.R_OK);
    readdirSync(dir);
  } catch {
    console.warn(`Workflow directory not readable: ${dir}`);
  }
}

Try / catch

try {
  await runWorkflow(name, opts);
} catch (e) {
  if (String((e as Error).message).startsWith('Error loading workflows')) {
    console.error('Check permissions on .archon/workflows/ and ~/.archon/workflows/:', (e as Error).message);
  }
}

Prevention

Keep .archon/workflows/ owned by the user running the CLI (avoid sudo-created files).
Use sane umasks when copying workflow packs; verify with `ls -la`.
Run a discovery pre-check after installing new workflow files.
Keep HOME set consistently between shells, services, and cron.

When it happens

Trigger: discoverWorkflowsWithConfig throws because .archon/workflows/ or ~/.archon/workflows/ is unreadable (EACCES), the directory does not exist in an unexpected way, a workflow YAML file is unreadable, or the config loader (loadConfig) itself throws during discovery.

Common situations: Workflow files created by root while the CLI runs as another user; restrictive umask after copying workflow packs; a symlink to an unreadable location; HOME changed so ~/.archon/workflows points somewhere odd; corrupted YAML triggering a load error surfaced through this path.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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