affaan-m/ECC · error · Error

ECC_ITO_CLI_EXECUTABLE does not point to a readable local…

Error message

ECC_ITO_CLI_EXECUTABLE does not point to a readable local Itô CLI file.

What it means

assertUsableExecutable canonicalizes the ECC_ITO_CLI_EXECUTABLE path with fs.realpathSync.native; if resolution fails (path does not exist, is unreachable, or permission errors occur), it throws this error stating the override does not point to a readable local Itô CLI file. A subsequent check enforces the canonical dist/bin/ito.js entry (that failure surfaces as a different error).

Solutions

1. Build the CLI first: cd into the repo and run npm ci && npm run build (verify dist/bin/ito.js exists)
2. Check the path resolves: ls -l "$ECC_ITO_CLI_EXECUTABLE" and realpath "$ECC_ITO_CLI_EXECUTABLE"
3. Fix typos or update the override to the current build location
4. Repair broken symlinks and verify read/execute permissions on the file

Example fix

// before
export ECC_ITO_CLI_EXECUTABLE=/opt/ito-compute-cli/dist/bin/ito.js # file missing
// after
cd /opt/ito-compute-cli && npm ci && npm run build
export ECC_ITO_CLI_EXECUTABLE=/opt/ito-compute-cli/dist/bin/ito.js

const fs = require('fs');
if (!fs.existsSync(process.env.ECC_ITO_CLI_EXECUTABLE)) {
  throw new Error('build the CLI first: npm ci && npm run build');
}

try {
  const exe = resolveItoExecutable(process.env);
} catch (e) {
  if (e.message.includes('does not point to a readable local')) {
    console.error('Run npm ci && npm run build in the CLI repo, or fix ECC_ITO_CLI_EXECUTABLE');
  } else throw e;
}

When it happens

Trigger: ECC_ITO_CLI_EXECUTABLE points to a nonexistent file, a deleted build artifact (dist not built), a directory instead of a file, or a path with permission/symlink-loop problems so realpathSync throws.

Common situations: Setting the env var before running npm ci/build so dist/bin/ito.js doesn't exist; cleaning the repo or switching branches and losing dist; pointing at a symlink whose target was removed; typos in the configured path.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• The canonical ito-compute-cli is unpublished and ECC will…
• all overlays must be readable local files
• all takes must be readable local files
• artifact byte count exceeded during reading
• artifact byte count mismatch

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

Appendix: source

Thrown at scripts/ito.js:212

      "run npm ci and npm run check, then set",
      `${EXECUTABLE_OVERRIDE} to the explicit absolute dist/bin/ito.js path.`,
    ].join(" "));
  }

  if (!path.isAbsolute(configured)) {
    throw new Error(
      `${EXECUTABLE_OVERRIDE} must be an absolute path explicitly configured by the operator.`
    );
  }
  return assertUsableExecutable(configured);
}

function assertUsableExecutable(candidate) {
  let canonicalCandidate;
  try {
    canonicalCandidate = fs.realpathSync.native(candidate);
  } catch {
    throw new Error(
      `${EXECUTABLE_OVERRIDE} does not point to a readable local Itô CLI file.`
    );
  }
  if (!isCanonicalItoEntry(canonicalCandidate)) {
    throw new Error(
      `${EXECUTABLE_OVERRIDE} must point to the canonical dist/bin/ito.js entry.`
    );
  }
  if (!isUsableExecutable(canonicalCandidate)) {
    throw new Error(
      `${EXECUTABLE_OVERRIDE} does not point to a readable local Itô CLI file.`
    );
  }
  return canonicalCandidate;
}

function isCanonicalItoEntry(candidate) {
  const pathSegments = path

View on GitHub (pinned to 8321021c54)