{"record":{"id":"25d7f8d84392fc9c","repo":"affaan-m/ECC","slug":"ecc-ito-cli-executable-does-not-point-to-a-readable-local-it","errorCode":null,"errorMessage":"ECC_ITO_CLI_EXECUTABLE does not point to a readable local Itô CLI file.","messagePattern":"ECC_ITO_CLI_EXECUTABLE does not point to a readable local Itô CLI file\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/ito.js","lineNumber":212,"sourceCode":"      \"run npm ci and npm run check, then set\",\n      `${EXECUTABLE_OVERRIDE} to the explicit absolute dist/bin/ito.js path.`,\n    ].join(\" \"));\n  }\n\n  if (!path.isAbsolute(configured)) {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} must be an absolute path explicitly configured by the operator.`\n    );\n  }\n  return assertUsableExecutable(configured);\n}\n\nfunction assertUsableExecutable(candidate) {\n  let canonicalCandidate;\n  try {\n    canonicalCandidate = fs.realpathSync.native(candidate);\n  } catch {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} does not point to a readable local Itô CLI file.`\n    );\n  }\n  if (!isCanonicalItoEntry(canonicalCandidate)) {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} must point to the canonical dist/bin/ito.js entry.`\n    );\n  }\n  if (!isUsableExecutable(canonicalCandidate)) {\n    throw new Error(\n      `${EXECUTABLE_OVERRIDE} does not point to a readable local Itô CLI file.`\n    );\n  }\n  return canonicalCandidate;\n}\n\nfunction isCanonicalItoEntry(candidate) {\n  const pathSegments = path","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/ito.js#L194-L230","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Build the CLI first: cd into the repo and run npm ci && npm run build (verify dist/bin/ito.js exists)","Check the path resolves: ls -l \"$ECC_ITO_CLI_EXECUTABLE\" and realpath \"$ECC_ITO_CLI_EXECUTABLE\"","Fix typos or update the override to the current build location","Repair broken symlinks and verify read/execute permissions on the file"],"exampleFix":"// before\nexport ECC_ITO_CLI_EXECUTABLE=/opt/ito-compute-cli/dist/bin/ito.js # file missing\n// after\ncd /opt/ito-compute-cli && npm ci && npm run build\nexport ECC_ITO_CLI_EXECUTABLE=/opt/ito-compute-cli/dist/bin/ito.js","handlingStrategy":"validation","validationCode":"const fs = require('fs');\nif (!fs.existsSync(process.env.ECC_ITO_CLI_EXECUTABLE)) {\n  throw new Error('build the CLI first: npm ci && npm run build');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const exe = resolveItoExecutable(process.env);\n} catch (e) {\n  if (e.message.includes('does not point to a readable local')) {\n    console.error('Run npm ci && npm run build in the CLI repo, or fix ECC_ITO_CLI_EXECUTABLE');\n  } else throw e;\n}","preventionTips":["Always build (npm ci && npm run build) before setting the override","Verify the path with realpath/ls after any branch switch or clean","Use realpath to detect broken symlinks in the configured path","Add a pre-flight fs.existsSync check in scripts that consume the override"],"tags":["filesystem","executable","environment"],"backgroundTag":"file-not-found","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}