{"record":{"id":"6d6662f0dcd64635","repo":"affaan-m/ECC","slug":"await-requires-a-file-path","errorCode":null,"errorMessage":"await requires a file path","messagePattern":"await requires a file path","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/plan-canvas.js","lineNumber":273,"sourceCode":"          data += chunk;\n        });\n        res.on('end', () => {\n          try {\n            resolve(JSON.parse(data.trim()));\n          } catch {\n            reject(new Error('await response was not JSON (server restarted?) - re-run await; feedback is never lost'));\n          }\n        });\n      }\n    );\n    req.setTimeout(0);\n    req.on('error', reject);\n    req.end();\n  });\n}\n\nasync function cmdAwait(file, args, { stateDir, port }) {\n  if (!file) throw new Error('await requires a file path');\n  if (!(await healthCheck(port))) {\n    return { status: 'no-server', hint: 'no canvas server is running; use `open` first', stateDir };\n  }\n  const reply = valueAfter(args, '--reply');\n  if (reply) {\n    const key = sessionKeyFor(canonicalizeArtifactPath(file));\n    await request(port, 'POST', `/api/session/${key}/reply`, { text: reply });\n  }\n  const timeoutRaw = valueAfter(args, '--timeout-ms');\n  const timeoutMs = timeoutRaw === null ? null : Number.parseInt(timeoutRaw, 10) || 0;\n  process.stderr.write('[plan-canvas] waiting for human feedback... leave this running (re-run if interrupted; queued feedback is never lost)\\n');\n  const result = await awaitRequest(port, sessionKeyFor(canonicalizeArtifactPath(file)), timeoutMs);\n  if (result.status === 'feedback') {\n    result.next_step = result.sessionEnded\n      ? 'The user sent this feedback and ended the session. Address it and report in chat; do not reopen the canvas uninvited.'\n      : 'Address the feedback, then run `ecc-plan-canvas await <file> --reply \"<what you changed>\"` to answer in the canvas and keep listening.';\n  } else if (result.status === 'ended') {\n    result.next_step =","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/plan-canvas.js#L255-L291","documentation":"cmdAwait implements `ecc-plan-canvas await <file>`, which blocks until the human sends feedback through the canvas. The file argument is mandatory because it is canonicalized to locate the session key; if no positional file path was supplied, the command fails fast with 'await requires a file path' instead of hanging or awaiting the wrong session.","triggerScenarios":"Running `ecc-plan-canvas await` with no positional argument — e.g. omitting the file, or invoking through a wrapper that drops argv, or typing only flags like `await --reply \"ok\"` where the arg parser consumed the path.","commonSituations":"Copy-pasting a documented command but skipping the placeholder; shell alias or npm script that lost the argument (`\"await\": \"ecc-plan-canvas await\"` invoked without args); a CI step where the plan file variable expanded to empty (`await $PLAN_FILE` with PLAN_FILE unset).","solutions":["Pass the plan file path explicitly: `ecc-plan-canvas await path/to/plan.md`.","If a shell variable holds the path, verify it is non-empty first (`: \"${PLAN_FILE:?PLAN_FILE not set}\"`) so it cannot expand to nothing.","Check any wrapper/alias to confirm it forwards positional arguments rather than swallowing them.","Use the relative or absolute path exactly as given to `open` so the canonicalization matches the open session."],"exampleFix":"# before (var may be empty)\necc-plan-canvas await $PLAN_FILE\n\n# after (fail fast if unset)\n: \"${PLAN_FILE:?set PLAN_FILE to your plan path}\"\necc-plan-canvas await \"$PLAN_FILE\"","handlingStrategy":"validation","validationCode":"if (!process.argv[3]) { console.error('usage: ecc-plan-canvas await <file>'); process.exit(2); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Make it a habit to pass the same plan path to open, await, typing, and end.","Use ${VAR:?msg} in shell scripts to fail fast on unset path variables.","Check wrapper scripts/aliases forward positional arguments.","Show usage text when the positional count is zero instead of a bare throw in your own tooling."],"tags":["cli","missing-argument","plan-canvas"],"backgroundTag":"missing-required-argument","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"}