affaan-m/ECC · error · Error

The local Itô CLI could not be started

Error message

The local Itô CLI could not be started: ${result.error.message}

What it means

invokeIto runs the canonical Itô CLI with spawnSync and forwards its stdout/stderr unchanged. If the child process could not be spawned at all, spawnSync populates result.error, and the bridge throws with the underlying reason. This indicates a process-start failure, not a non-zero exit from the CLI itself.

Solutions

  1. Read result.error.message in the thrown text (ENOENT/EACCES/EAGAIN) and fix that root cause — e.g. EACCES: chmod +x / re-checkout; ENOENT: rebuild dist.
  2. Rebuild the canonical CLI (npm ci && npm run build in cli/ito-compute-cli) to restore a healthy dist/bin/ito.js.
  3. Verify the Node runtime running ECC (process.execPath) is a working, sufficiently new Node; update Node if the CLI fails on startup syntax.
  4. Check ulimit -u / container seccomp policies if the message is EAGAIN or permission-related.

Example fix

// before
$ ecc ito status
Error: The local Itô CLI could not be started: spawnSync /path/dist/bin/ito.js EACCES
// after
chmod +x /path/ito-cloud-runtime/cli/ito-compute-cli/dist/bin/ito.js
$ ecc ito status   # proceeds
Defensive patterns

Strategy: try-catch

Validate before calling

const fs = require('fs');
const p = process.env.ECC_ITO_CLI_EXECUTABLE;
if (!p || !fs.existsSync(p) || process.version < 'v20') console.warn('Itô CLI preflight failed');

Try / catch

try { const code = await invokeIto(args); } catch (e) {
  if (e.message.startsWith('The local Itô CLI could not be started')) {
    const m = e.message.match(/ (EACCES|ENOENT|EAGAIN)/);
    console.error('Spawn failed:', m && m[1], '— rebuild dist or fix permissions');
  } else throw e;
}

Prevention

When it happens

Trigger: Running an ecc ito subcommand when the node binary in process.execPath is missing/unusable, the CLI script crashed at startup (e.g. ENOENT on a dynamic require, EACCES on the file), spawn limits are hit (EAGAIN), or the interpreter cannot execute dist/bin/ito.js.

Common situations: Node version too old for the CLI's syntax; dist build corrupted; disk full or ulimit restrictions; antivirus/seatbelt blocking child spawn; running inside a sandbox where exec of the checkout path is denied.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at scripts/ito.js:288

  const isNodeQualification = command === "evals";
  const isDeviceLogin = command === "login";
  const result = spawnSync(invocation.executable, invocation.args, {
    cwd: process.cwd(),
    encoding: "utf8",
    // Keep policy helpers immutable for callers, but give child-process
    // instrumentation its own mutable copy (for example NODE_V8_COVERAGE).
    env: { ...createSafeItoInvocationEnvironment(environment, args) },
    stdio: isDeviceLogin ? "inherit" : ["pipe", "pipe", "pipe"],
    maxBuffer: MAX_OUTPUT_BYTES,
    timeout: isNodeQualification ? NODE_QUALIFICATION_TIMEOUT_MS : undefined,
    shell: false,
    windowsHide: true,
  });

  if (result.stdout) process.stdout.write(result.stdout);
  if (result.stderr) process.stderr.write(result.stderr);
  if (result.error) {
    throw new Error(`The local Itô CLI could not be started: ${result.error.message}`);
  }
  if (typeof result.status === "number") return result.status;
  if (result.signal) {
    throw new Error(`The local Itô CLI terminated by signal ${result.signal}.`);
  }
  return 1;
}

function main(argv = process.argv.slice(2), environment = process.env) {
  try {
    const parsed = parseArgs(argv, environment);
    if (parsed.help) {
      showHelp();
      return 0;
    }
    const executable = resolveItoExecutable(environment);
    return invokeIto(executable, parsed.invocationArgs, environment);
  } catch (error) {

View on GitHub (pinned to 8321021c54)