affaan-m/ECC · error · Error

await requires a file path

Error message

await requires a file path

What it means

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.

Solutions

1. Pass the plan file path explicitly: `ecc-plan-canvas await path/to/plan.md`.
2. 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.
3. Check any wrapper/alias to confirm it forwards positional arguments rather than swallowing them.
4. Use the relative or absolute path exactly as given to `open` so the canonicalization matches the open session.

Example fix

# before (var may be empty)
ecc-plan-canvas await $PLAN_FILE

# after (fail fast if unset)
: "${PLAN_FILE:?set PLAN_FILE to your plan path}"
ecc-plan-canvas await "$PLAN_FILE"

if (!process.argv[3]) { console.error('usage: ecc-plan-canvas await <file>'); process.exit(2); }

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• end requires a file path
• typing requires a file path
• An executable is required after --.
• An install config path is required
• At least one --target is required for handoffs.

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

Appendix: source

Thrown at scripts/plan-canvas.js:273

          data += chunk;
        });
        res.on('end', () => {
          try {
            resolve(JSON.parse(data.trim()));
          } catch {
            reject(new Error('await response was not JSON (server restarted?) - re-run await; feedback is never lost'));
          }
        });
      }
    );
    req.setTimeout(0);
    req.on('error', reject);
    req.end();
  });
}

async function cmdAwait(file, args, { stateDir, port }) {
  if (!file) throw new Error('await requires a file path');
  if (!(await healthCheck(port))) {
    return { status: 'no-server', hint: 'no canvas server is running; use `open` first', stateDir };
  }
  const reply = valueAfter(args, '--reply');
  if (reply) {
    const key = sessionKeyFor(canonicalizeArtifactPath(file));
    await request(port, 'POST', `/api/session/${key}/reply`, { text: reply });
  }
  const timeoutRaw = valueAfter(args, '--timeout-ms');
  const timeoutMs = timeoutRaw === null ? null : Number.parseInt(timeoutRaw, 10) || 0;
  process.stderr.write('[plan-canvas] waiting for human feedback... leave this running (re-run if interrupted; queued feedback is never lost)\n');
  const result = await awaitRequest(port, sessionKeyFor(canonicalizeArtifactPath(file)), timeoutMs);
  if (result.status === 'feedback') {
    result.next_step = result.sessionEnded
      ? 'The user sent this feedback and ended the session. Address it and report in chat; do not reopen the canvas uninvited.'
      : 'Address the feedback, then run `ecc-plan-canvas await <file> --reply "<what you changed>"` to answer in the canvas and keep listening.';
  } else if (result.status === 'ended') {
    result.next_step =

View on GitHub (pinned to 8321021c54)