{"record":{"id":"d559ce081fb2d24c","repo":"affaan-m/ECC","slug":"artifact-not-found-file","errorCode":null,"errorMessage":"artifact not found: ${file}","messagePattern":"artifact not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/plan-canvas.js","lineNumber":226,"sourceCode":"  }\n}\n\nfunction output(payload) {\n  process.stdout.write(`${JSON.stringify(payload, null, 2)}\\n`);\n}\n\nasync function cmdStatus({ stateDir, port }) {\n  const health = await healthCheck(port);\n  if (!health) {\n    return { server: 'not running', hint: 'open an artifact to start one', stateDir };\n  }\n  const sessions = await request(port, 'GET', '/api/sessions');\n  return { server: `http://${DEFAULT_HOST}:${port}`, version: health.version, sessions: sessions.body.sessions };\n}\n\nasync function cmdOpen(file, args, { stateDir, port }) {\n  if (!file) throw new Error('open requires a file path');\n  if (!fs.existsSync(path.resolve(file))) throw new Error(`artifact not found: ${file}`);\n  await ensureServer({ stateDir, port });\n  const res = await request(port, 'POST', '/api/sessions', {\n    file: path.resolve(file),\n    reopen: args.includes('--reopen')\n  });\n  if (res.statusCode === 409) return res.body;\n  if (res.statusCode !== 200) throw new Error(res.body.error || `open failed (HTTP ${res.statusCode})`);\n  const url = `http://${DEFAULT_HOST}:${port}${res.body.url}`;\n  const launched = args.includes('--no-open') ? false : openBrowser(url);\n  return {\n    status: 'open',\n    url,\n    browser: launched ? 'opened' : 'not opened',\n    next_step:\n      'Run `ecc-plan-canvas await <file>` and leave it running; it returns when the human sends feedback, a verdict, or ends the session.'\n  };\n}\n","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/plan-canvas.js#L208-L244","documentation":"cmdOpen resolves the given file path and checks fs.existsSync before creating a session; if the file does not exist on disk it throws this error, echoing the original (unresolved) path so the user can see what was looked for.","triggerScenarios":"Running `plan-canvas open relative/path.html` from the wrong working directory; a typo in the filename; the plan file deleted or renamed since it was generated; passing a directory path instead of the artifact file.","commonSituations":"Path built relative to a project root but executed from repo root or /tmp; case-sensitive filesystem mismatches (Plan.HTML vs plan.html); artifacts in a gitignored build dir that a clean removed; symlink targets missing.","solutions":["Verify the path exists: run `ls -l <file>` (or the absolute equivalent) before invoking open.","Use an absolute path or run from the directory that makes the relative path correct.","Check spelling and case of the filename, especially on Linux.","Regenerate the plan/artifact if it was deleted, and re-run the open command."],"exampleFix":"// before\nnode scripts/plan-canvas.js open ./.ecc-design/plan.html   # file not there\n// after\nnode scripts/plan-canvas.js open /abs/path/to/project/.ecc-design/plan.html","handlingStrategy":"validation","validationCode":"const resolved = path.resolve(file);\nif (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {\n  console.error(`artifact not found or not a file: ${file}`);\n  process.exit(2);\n}","typeGuard":"function isExistingFile(v) {\n  try { return typeof v === 'string' && fs.statSync(path.resolve(v)).isFile(); } catch { return false; }\n}","tryCatchPattern":"try {\n  await cmdOpen(file, args, { stateDir, port });\n} catch (err) {\n  if (err.message.startsWith('artifact not found:')) {\n    console.error(`${err.message}\\ncwd=${process.cwd()} — use an absolute path or fix the relative path.`);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Use absolute paths in scripts and CI to avoid cwd dependence","`ls -l` the exact path (respecting case sensitivity) before invoking open","Regenerate artifacts that live in cleaned/gitignored directories","Guard symlinked paths — verify the target file exists too"],"tags":["file","not-found","cli"],"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"}