affaan-m/ECC · error · Error

Invalid ${name} value: expected a path

Error message

Invalid ${name} value: expected a path

What it means

Thrown by pathValueAfter at scripts/lib/control-pane/server.js:54-61 when a parsed argument value is empty or starts with '-' (i.e. looks like another flag, not a path). pathValueAfter is a stricter variant of valueAfter used specifically for path-typed options; it forbids flag-shaped values to catch missing-argument mistakes. In parseArgs it is currently applied only to --state-db (server.js:78), so the interpolated name will normally be '--state-db'. Other path-like options (--db, --config) use the more permissive valueAfter and do not trigger this error.

Source

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

    '',
    'Options:',
    '  --state-db <path>  Read agent work items from an ECC state-store database',
    '  --read-only        Disable action execution endpoints',
    '  --no-open          Do not open a browser after the server starts',
    '  --help             Show this help'
  ].join('\n');
}

function valueAfter(args, name) {
  const index = args.indexOf(name);
  return index >= 0 ? args[index + 1] : null;
}

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,

View on GitHub (pinned to 01e15490f0)

Solutions

1. Provide a non-flag path: `--state-db /path/to/state.db`.
2. If the value legitimately starts with '-', use an absolute path (which starts with '/', not '-').
3. Quote shell expansions to avoid empty tokens: `--state-db "$STATE_DB"` and ensure STATE_DB is set.
4. If you want --state-db to be optional, simply omit it — pathValueAfter returns null when the flag is absent (server.js:56).

Example fix

// before
$ node scripts/control-pane.js --state-db --read-only
// after
$ node scripts/control-pane.js --state-db /home/u/state.db --read-only

function parsePathOption(argv, name) {
  const i = argv.indexOf(name);
  if (i < 0) return null;
  const v = argv[i + 1];
  if (!v || v.startsWith('-')) throw new Error(`Invalid ${name} value: expected a path`);
  return v;
}
parsePathOption(process.argv.slice(2), '--state-db');

When it happens

Trigger: `node scripts/control-pane.js --state-db` (no value follows); `--state-db --read-only` (next token is a flag); `--state-db ''` (empty value); `--state-db -h`. The check at server.js:57 fires when value is falsy or starts with '-'.

Common situations: Operator forgets to pass the path after --state-db; a script concatenates flags and drops the value during argv construction; copy/paste from docs that line-break between flag and value; an empty environment variable expansion produces an empty token.

Related errors

• Invalid --port value: ${portValue}
• --config-dir must be an existing absolute directory.
• ${EXECUTABLE_OVERRIDE} must be an absolute path explicitly c
• ${EXECUTABLE_OVERRIDE} does not point to a readable local It
• ${EXECUTABLE_OVERRIDE} must point to the canonical dist/bin/

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