What causes "Cannot access command file at ${path}: ${err.message}" in coleam00/Archon?

Check the 'command_file_access_error' log entry for the underlying errno code and path.

Cannot access command file at ${path}: ${err.message}

Error message

Cannot access command file at ${path}: ${err.message}

What it means

commandFileExists checks for a command file's presence; ENOENT is mapped to false, but any other stat/access failure (permissions, I/O errors) is deliberately not swallowed — it is logged ('command_file_access_error') and rethrown with this message. It signals the engine could not determine the file's existence due to an unexpected filesystem error.

Source

Thrown at packages/core/src/orchestrator/orchestrator.ts:22

 */
import { readFile as fsReadFile, access as fsAccess } from 'fs/promises';

// Wrapper function for reading files - allows mocking without polluting fs/promises globally
export async function readCommandFile(path: string): Promise<string> {
  return fsReadFile(path, 'utf-8');
}
export async function commandFileExists(path: string): Promise<boolean> {
  try {
    await fsAccess(path);
    return true;
  } catch (error) {
    const err = error as NodeJS.ErrnoException;
    if (err.code === 'ENOENT') {
      return false;
    }
    // Unexpected errors (permissions, I/O) should not be swallowed
    getLog().error({ err, path, code: err.code }, 'command_file_access_error');
    throw new Error(`Cannot access command file at ${path}: ${err.message}`);
  }
}
import { createLogger } from '@archon/paths';

/** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
let cachedLog: ReturnType<typeof createLogger> | undefined;
function getLog(): ReturnType<typeof createLogger> {
  if (!cachedLog) cachedLog = createLogger('orchestrator');
  return cachedLog;
}
import {
  IPlatformAdapter,
  Conversation,
  Codebase,
  ConversationNotFoundError,
  isWebAdapter,
} from '../types';
import type { IsolationHints, IsolationEnvironmentRow } from '@archon/isolation';

View on GitHub (pinned to 0773b97458)

Solutions

Check the 'command_file_access_error' log entry for the underlying errno code and path.
Fix permissions on the file and its parent directories (chmod/chown).
Verify the volume/mount containing the path is available inside the environment.
Confirm the configured path is correct and not pointing at a broken symlink.

Example fix

// before
$ ls -la /home/user/.archon/commands  # permission denied
// after
$ sudo chown -R archon:archon /home/user/.archon/commands
$ chmod u+rx /home/user/.archon/commands

Defensive patterns

Strategy: try-catch

Validate before calling

try { fs.accessSync(dir, fs.constants.R_OK | fs.constants.X_OK); } catch (e) { console.error('Commands dir not accessible:', e.code); }

Type guard

function isENOENT(e) {
  return e != null && typeof e === 'object' && e.code === 'ENOENT';
}

Try / catch

try {
  await loadCommands(path);
} catch (e) {
  if (!isENOENT(e)) {
    console.error(`Command file access failed (${e.code ?? 'unknown'}) at ${path}; fix permissions/mount`);
  }
  throw e;
}

Prevention

Run the process as a user with read/execute access to the commands directory.
Verify volumes/mounts are present in containers before startup.
Treat non-ENOENT access errors as environment problems, not 'file missing'.

When it happens

Trigger: The path's parent directory lacks read/search permission; the path is on a disconnected/unmounted volume; a symlink loop or EIO from failing disk causes fs access to throw with a code other than ENOENT.

Common situations: Running the orchestrator as a different user than the file owner; container volume not mounted; read-only or corrupted filesystem; over-restrictive umask on the commands directory.

Related errors

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