affaan-m/ECC · error · Error

Invalid --port value

Error message

Invalid --port value: ${portValue}

What it means

The control-pane server's parseArgs validates --port: the value is parsed with Number.parseInt and must be a finite number in [0, 65535]. Anything else (non-numeric text, negative, or above 65535) throws 'Invalid --port value: <value>'.

Solutions

1. Pass a numeric port between 0 and 65535: --port 8765
2. Verify the value with: node -e "const p=parseInt(process.argv[1],10); console.log(Number.isFinite(p)&&p>=0&&p<=65535)" 8765
3. Fix the shell variable or template that injects a non-numeric port
4. Omit --port to use the default 8765

Example fix

// before
$ node server.js --port "8080 "
// after
$ node server.js --port 8080

const port = Number.parseInt(portArg, 10);
if (!Number.isFinite(port) || port < 0 || port > 65535) throw new Error(`bad port: ${portArg}`);

const isValidPort = (v) => { const p = Number.parseInt(v, 10); return Number.isFinite(p) && p >= 0 && p <= 65535; };

try { const opts = parseArgs(process.argv); } catch (e) {
  if (String(e.message).startsWith('Invalid --port')) console.error('Use a numeric port 0-65535, e.g. --port 8765');
  else throw e;
}

When it happens

Trigger: Running `node server.js --port abc`, `--port 99999`, `--port -1`, or `--port 8765x`; also an empty value that falls through to the default would not throw, but any explicit bad value does.

Common situations: Copy-pasting a port with stray characters; confusing the port with a PID; using a port above the TCP limit; env substitution producing garbage ($PORT unset with set -u off giving empty string is fine, but a templating bug can inject text).

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• all overlays must be readable local files
• all takes must be readable local files
• Arguments must not contain NUL bytes.
• asset name must be a simple filename stem (letters, digits…
• At least one guided harness must be selected

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

Appendix: source

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

}

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 8321021c54)