affaan-m/ECC · error · Error

Invalid --port value: ${portValue}

Error message

Invalid --port value: ${portValue}

What it means

Thrown by parseArgs at scripts/lib/control-pane/server.js:67-71 when the --port value cannot be parsed as a finite integer in [0, 65535]. The default port is 8765 (server.js:67) when --port is absent, so this only fires when --port is supplied with a malformed value. Number.parseInt is base-10; NaN, negatives, and values above 65535 are all rejected. Note that the check does not reserved-block privileged ports — port 80 or 1024 will pass the validator; binding will then fail separately if the user lacks capabilities.

Source

Thrown at scripts/lib/control-pane/server.js:70

}

function pathValueAfter(args, name) {
  const value = valueAfter(args, name);
  if (value === null) return null;
  if (!value || value.startsWith('-')) {
    throw new Error(`Invalid ${name} value: expected a path`);
  }
  return value;
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const help = args.includes('--help') || args.includes('-h');
  const host = valueAfter(args, '--host') || '127.0.0.1';
  const portValue = valueAfter(args, '--port') || '8765';
  const port = Number.parseInt(portValue, 10);
  if (!Number.isFinite(port) || port < 0 || port > 65535) {
    throw new Error(`Invalid --port value: ${portValue}`);
  }

  return {
    help,
    host,
    port,
    dbPath: valueAfter(args, '--db'),
    stateDbPath: pathValueAfter(args, '--state-db'),
    configPath: valueAfter(args, '--config'),
    query: valueAfter(args, '--query') || '',
    openBrowser: !args.includes('--no-open'),
    allowActions: !args.includes('--read-only')
  };
}

function sendJson(res, statusCode, payload) {
  const body = JSON.stringify(payload, null, 2);
  res.writeHead(statusCode, {

View on GitHub (pinned to 01e15490f0)

Solutions

1. Pass a base-10 integer in [0, 65535]: `--port 8765`.
2. Omit --port to use the default 8765.
3. Use `--port 0` if you want the OS to assign a free port (the server reports the actual port via the `url` getter at server.js:336-340).
4. Sanitize upstream: in a wrapper, validate with `[ "$P" -ge 0 ] && [ "$P" -le 65535 ]` before forwarding.

Example fix

// before
$ node scripts/control-pane.js --port 99999
// after
$ node scripts/control-pane.js --port 8765

function parsePort(value, fallback = 8765) {
  if (value == null) return fallback;
  const p = Number.parseInt(value, 10);
  if (!Number.isFinite(p) || p < 0 || p > 65535) {
    throw new Error(`Invalid --port value: ${value}`);
  }
  return p;
}
parsePort(process.env.CONTROL_PANE_PORT, 8765);

function isValidPortNumber(value) {
  return Number.isInteger(value) && value >= 0 && value <= 65535;
}

When it happens

Trigger: `--port abc`; `--port 70000`; `--port -1`; `--port 3.14` (parseInt yields 3, which is actually valid — but `--port 0x10` yields 0 because parseInt(_, 10) stops at 'x', also valid); `--port 99999999999`. Any value where Number.isFinite(port) is false or port is outside [0, 65535].

Common situations: Operator typo (`--port 8865` intended, typed `--port 88f65`); copy/paste of a port from a URL with the protocol attached (`--port https://...`); a config script passing a stringly-typed value; intending to use port 0 (OS-assigned) which IS allowed and not the source of the error — the error is for out-of-range/non-numeric.

Related errors

• Invalid ${name} value: expected a path
• invalid plan-canvas server port: ${port}
• No install profile, module IDs, included components, or lega
• decisions does not accept a session ID when --all is set
• graph sync does not accept a session ID when --all is set

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/0dd00c7f7e984876. Report an issue: GitHub.