affaan-m/ECC · error

--config-dir must exist and contain a regular sixtytwo.yaml

Error message

--config-dir must exist and contain a regular sixtytwo.yaml before any process is started.

What it means

Thrown by the catch block at scripts/ito.js:134-137 of validateNodeQualificationArgs. It fires for ANY failure inside the preceding try{}: fs.realpathSync.native failing (ENOENT, EACCES), fs.statSync failing, the inner validation throw at line 132, or the isDirectory/isFile checks returning false. Because the catch is parameter-less and unconditional, this single message masks three distinct failure modes (path resolution, dir-ness, file-ness). It is the message users actually see when --config-dir is wrong for `ecc ito evals`.

Source

Thrown at scripts/ito.js:135

  requiredOptionValue(args, "--cluster");
  const nodes = requiredOptionValue(args, "--nodes");
  if (!nodes.split(",").every((node) => node.trim().length > 0)) {
    throw new Error("--nodes must explicitly list one or more non-empty nodes.");
  }
  const configDirectory = requiredOptionValue(args, "--config-dir");
  if (!path.isAbsolute(configDirectory)) {
    throw new Error("--config-dir must be an existing absolute directory.");
  }
  try {
    const resolved = fs.realpathSync.native(configDirectory);
    if (
      !fs.statSync(resolved).isDirectory()
      || !fs.statSync(path.join(resolved, "sixtytwo.yaml")).isFile()
    ) {
      throw new Error("invalid qualification configuration");
    }
  } catch {
    throw new Error(
      "--config-dir must exist and contain a regular sixtytwo.yaml before any process is started."
    );
  }
}

function parseArgs(argv, environment = process.env) {
  const args = [...argv];
  if (
    args.length === 0
    || args.includes("--help")
    || args.includes("-h")
  ) {
    return Object.freeze({ help: true, invocationArgs: [] });
  }

  if (environment.ECC_DRY_RUN === "1" || args.includes("--dry-run")) {
    throw new Error(
      "Itô compute has no paper or dry-run success mode. No CLI operation was invoked."

View on GitHub (pinned to 01e15490f0)

Solutions

1. Verify the path exists and is a directory: `test -d "$CONFIG_DIR" && ls -la "$CONFIG_DIR"`.
2. Verify sixtytwo.yaml exists as a regular file with the exact name: `test -f "$CONFIG_DIR/sixtytwo.yaml"`.
3. Check permissions on every path component (realpathSync and statSync both need read/traverse): `namei -l "$CONFIG_DIR/sixtytwo.yaml"`.
4. Resolve symlinks manually first (`readlink -f`) to confirm what realpathSync.native will return.

const fs = require('fs');
const path = require('path');
function preflightConfigDir(configDirectory) {
  const errors = [];
  let resolved;
  try { resolved = fs.realpathSync.native(configDirectory); }
  catch (e) { errors.push(`cannot resolve: ${e.message}`); return errors; }
  if (!fs.statSync(resolved).isDirectory()) errors.push(`${resolved} is not a directory`);
  const yaml = path.join(resolved, 'sixtytwo.yaml');
  try { if (!fs.statSync(yaml).isFile()) errors.push(`${yaml} is not a regular file`); }
  catch (e) { errors.push(`${yaml} missing or unreadable: ${e.message}`); }
  return errors;
}
// run before `ecc ito evals`
const issues = preflightConfigDir(process.env.ITO_CONFIG_DIR);
if (issues.length) { console.error(issues); process.exit(1); }

try {
  // call ecc ito evals via spawn
} catch (err) {
  if (err.message.includes('--config-dir must exist and contain a regular sixtytwo.yaml')) {
    // re-run preflightConfigDir to give the operator the precise failure
  }
}

When it happens

Trigger: `ecc ito evals --cluster <id> --live-sixtytwo --nodes <list> --config-dir <abs>` where <abs> does not exist, is not readable, is not a directory, OR does not contain a regular file named exactly sixtytwo.yaml. Also fires when sixtytwo.yaml exists but is a directory or special file.

Common situations: Operator forgot to create the config dir; or created it but mistyped the yaml filename (sixtyTwo.yaml, sixtytwo.yml — the check is case-sensitive and only accepts sixtytwo.yaml); or pointed at a symlink loop / permission-restricted path. Also commonly hit when copying a config layout from another machine without the yaml file.

Related errors

• --config-dir must be an existing absolute directory.
• invalid qualification configuration
• ${EXECUTABLE_OVERRIDE} does not point to a readable local It
• --json may only be provided once
• Unsupported Itô command "${command || "(missing)"}"; ECC per

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/5b7d834bbf82cd74. Report an issue: GitHub.