{"record":{"id":"7c5b5910302abbfb","repo":"affaan-m/ECC","slug":"invalid-plan-canvas-server-port-port","errorCode":null,"errorMessage":"invalid plan-canvas server port: ${port}","messagePattern":"invalid plan-canvas server port: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/plan-canvas.js","lineNumber":96,"sourceCode":"  return index >= 0 && index + 1 < args.length ? args[index + 1] : null;\n}\n\nfunction serverInfoPath(stateDir) {\n  return path.join(stateDir, 'server.json');\n}\n\nfunction readServerInfo(stateDir) {\n  try {\n    return JSON.parse(fs.readFileSync(serverInfoPath(stateDir), 'utf8'));\n  } catch {\n    return null;\n  }\n}\n\nfunction validatePort(port) {\n  const value = Number(port);\n  if (!Number.isInteger(value) || value < 0 || value > 65535) {\n    throw new Error(`invalid plan-canvas server port: ${port}`);\n  }\n  return value;\n}\n\nfunction validateRequestPath(requestPath) {\n  if (typeof requestPath !== 'string' || !requestPath.startsWith('/')) {\n    throw new Error('plan-canvas request path must be root-relative');\n  }\n  const url = new URL(requestPath, `http://${DEFAULT_HOST}`);\n  if (url.hostname !== DEFAULT_HOST) {\n    throw new Error('plan-canvas request path must stay on the loopback server');\n  }\n  if (!SAFE_REQUEST_PATHS.has(url.pathname) && !SESSION_REPLY_PATH.test(url.pathname)) {\n    throw new Error(`unsupported plan-canvas request path: ${url.pathname}`);\n  }\n  return `${url.pathname}${url.search}`;\n}\n","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/plan-canvas.js#L78-L114","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nPLAN_CANVAS_PORT=localhost:4173 node scripts/plan-canvas.js open plan.html\n// after\nPLAN_CANVAS_PORT=4173 node scripts/plan-canvas.js open plan.html","handlingStrategy":"validation","validationCode":"const n = Number(process.env.PLAN_CANVAS_PORT);\nif (!Number.isInteger(n) || n < 0 || n > 65535) {\n  throw new Error(`PLAN_CANVAS_PORT must be an integer 0-65535, got: ${process.env.PLAN_CANVAS_PORT}`);\n}","typeGuard":"function isValidPort(v) { const n = Number(v); return Number.isInteger(n) && n >= 0 && n <= 65535; }","tryCatchPattern":"try {\n  await cmdOpen(file, args, { stateDir, port });\n} catch (err) {\n  if (err.message.startsWith('invalid plan-canvas server port:')) {\n    console.error('Fix the PORT value: bare integer 0-65535, no host prefix.');\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["configuration","validation","port"],"backgroundTag":"invalid-config-value","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"}