What causes "invalid plan-canvas server port: ${port}" in affaan-m/ECC?

Set the port to a plain integer between 0 and 65535, e.g. 4173.

affaan-m/ECC · error · Error

invalid plan-canvas server port

Error message

invalid plan-canvas server port: ${port}

What it means

validatePort in scripts/plan-canvas.js coerces the configured port with Number() and requires an integer in [0, 65535]. Any non-numeric string, NaN, negative number, float, or value above 65535 throws this error before a server is started.

Solutions

Set the port to a plain integer between 0 and 65535, e.g. 4173.
Inspect the env var or CLI argument being interpolated; echo it to confirm its raw value.
Do not include a protocol or hostname — use the bare number only.
If port 0 (OS-assigned) is unintended, pick an explicit port so the resolved value is predictable.

Example fix

// before
PLAN_CANVAS_PORT=localhost:4173 node scripts/plan-canvas.js open plan.html
// after
PLAN_CANVAS_PORT=4173 node scripts/plan-canvas.js open plan.html

Defensive patterns

Strategy: validation

Validate before calling

const n = Number(process.env.PLAN_CANVAS_PORT);
if (!Number.isInteger(n) || n < 0 || n > 65535) {
  throw new Error(`PLAN_CANVAS_PORT must be an integer 0-65535, got: ${process.env.PLAN_CANVAS_PORT}`);
}

Type guard

function isValidPort(v) { const n = Number(v); return Number.isInteger(n) && n >= 0 && n <= 65535; }

Try / catch

try {
  await cmdOpen(file, args, { stateDir, port });
} catch (err) {
  if (err.message.startsWith('invalid plan-canvas server port:')) {
    console.error('Fix the PORT value: bare integer 0-65535, no host prefix.');
    process.exit(2);
  }
  throw err;
}

Prevention

Store the port as a bare integer — never host:port or URL form
Validate env-derived ports at config load time, not at request time
Document expected port values in the project .env.example
Use well-known constants (4173) rather than ad-hoc strings in CI

When it happens

Trigger: Passing an invalid --port CLI value to cmdOpen/cmdStatus, a PLAN_CANVAS_PORT-style env var set to `"abc"` or `"99999"`, or programmatic requestOptions callers supplying a float like 8080.5 — all reach the `!Number.isInteger(value) || value < 0 || value > 65535` check.

Common situations: Typo in the port environment variable; copying a full host:port string (`localhost:4173`) into a port field; port 0 misuse confusion; YAML/env config with quotes or whitespace producing NaN.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at scripts/plan-canvas.js:96

  return index >= 0 && index + 1 < args.length ? args[index + 1] : null;
}

function serverInfoPath(stateDir) {
  return path.join(stateDir, 'server.json');
}

function readServerInfo(stateDir) {
  try {
    return JSON.parse(fs.readFileSync(serverInfoPath(stateDir), 'utf8'));
  } catch {
    return null;
  }
}

function validatePort(port) {
  const value = Number(port);
  if (!Number.isInteger(value) || value < 0 || value > 65535) {
    throw new Error(`invalid plan-canvas server port: ${port}`);
  }
  return value;
}

function validateRequestPath(requestPath) {
  if (typeof requestPath !== 'string' || !requestPath.startsWith('/')) {
    throw new Error('plan-canvas request path must be root-relative');
  }
  const url = new URL(requestPath, `http://${DEFAULT_HOST}`);
  if (url.hostname !== DEFAULT_HOST) {
    throw new Error('plan-canvas request path must stay on the loopback server');
  }
  if (!SAFE_REQUEST_PATHS.has(url.pathname) && !SESSION_REPLY_PATH.test(url.pathname)) {
    throw new Error(`unsupported plan-canvas request path: ${url.pathname}`);
  }
  return `${url.pathname}${url.search}`;
}

View on GitHub (pinned to 8321021c54)