affaan-m/ECC · error · Error

is required exactly once for live node qualification.

Error message

${option} is required exactly once for live node qualification.

What it means

requiredOptionValue() in ito.js enforces that a given option flag appears exactly once in the argument list for live node qualification. Zero occurrences means a mandatory option is missing; more than one is ambiguous. Both cases throw this error before any process starts.

Solutions

1. Ensure the flagged option (e.g. --cluster <value>) is present exactly once in the command.
2. In shell wrappers, guard: if [ -z "$CLUSTER" ]; then echo "--cluster required"; exit 1; fi.
3. Remove duplicate occurrences of the flag, keeping a single one.

Example fix

// before
ito --live-sixtytwo --nodes node-a
// after
ito --live-sixtytwo --cluster prod --nodes node-a

const count = args.filter(a => a === option).length; if (count !== 1) throw new Error(`${option} must appear exactly once`);

try { runQualification(args); } catch (e) { if (e.message.includes('required exactly once')) { console.error(`${e.message} — check your command line`); process.exit(2); } throw e; }

When it happens

Trigger: Calling a live-node-qualification command missing the option (e.g. no --cluster) or repeating it (e.g. --cluster a --cluster b), so indexes.length !== 1 in requiredOptionValue.

Common situations: Shell scripts where a variable holding the cluster value is empty, leaving the flag silently dropped; duplicated flags after concatenating argument arrays; users unaware the option is mandatory for --live-sixtytwo runs.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Missing issue number.
• Missing --repo <owner/repo>.
• open requires a file path
• skills:amendify requires --skill
• skills:evaluate requires --skill

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/ec7f763c0a6742de. Report an issue: GitHub.

Appendix: source

Thrown at scripts/ito.js:97

forward ITO_API_KEY directly when configured; ITO_AUTH_MODE=legacy is not
required. The canonical client stores device credentials in macOS Keychain by
default; file-token fallback remains explicit and must use restrictive settings.
Never put a key or token in arguments, tracked files, or chat.

Live node qualification requires ITO_ENABLE_SIXTYTWO_LIVE=1,
--live-sixtytwo, an explicit node list, and an existing absolute config
directory. It forwards only named SIXTYTWO_API_TOKEN/SIXTYTWO_TOKEN and SSH
agent state; ITO_API_KEY is intentionally excluded. The canonical CLI requires
sixtytwo-cli==0.3.33 and fails closed.
`);
}

function requiredOptionValue(args, option) {
  const indexes = args
    .map((value, index) => (value === option ? index : -1))
    .filter((index) => index >= 0);
  if (indexes.length !== 1) {
    throw new Error(`${option} is required exactly once for live node qualification.`);
  }
  const value = args[indexes[0] + 1];
  if (!value?.trim() || value.startsWith("--")) {
    throw new Error(`${option} requires a non-empty value for live node qualification.`);
  }
  return value;
}

function validateNodeQualificationArgs(args, environment) {
  if (environment.ITO_ENABLE_SIXTYTWO_LIVE !== "1") {
    throw new Error(
      "Live node qualification requires ITO_ENABLE_SIXTYTWO_LIVE=1 before any process is started."
    );
  }
  if (args.filter((value) => value === "--live-sixtytwo").length !== 1) {
    throw new Error(
      "Live node qualification requires --live-sixtytwo exactly once before any process is started."
    );

View on GitHub (pinned to 8321021c54)