openai/codex-plugin-cc · error · Error

Usage: node scripts/app-server-broker.mjs serve --endpoint <

Error message

Usage: node scripts/app-server-broker.mjs serve --endpoint <value> [--cwd <path>] [--pid-file <path>]

What it means

The app-server-broker.mjs script accepts exactly one subcommand, 'serve', as its first positional argument. If process.argv[2] is anything else (including undefined), the script throws this usage error and exits non-zero via the top-level main().catch handler. This is a hard CLI contract enforcement, not a recoverable runtime condition.

Source

Thrown at plugins/codex/scripts/app-server-broker.mjs:51

  socket.write(`${JSON.stringify(message)}\n`);
}

function isInterruptRequest(message) {
  return message?.method === "turn/interrupt";
}

function writePidFile(pidFile) {
  if (!pidFile) {
    return;
  }
  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
  fs.writeFileSync(pidFile, `${process.pid}\n`, "utf8");
}

async function main() {
  const [subcommand, ...argv] = process.argv.slice(2);
  if (subcommand !== "serve") {
    throw new Error("Usage: node scripts/app-server-broker.mjs serve --endpoint <value> [--cwd <path>] [--pid-file <path>]");
  }

  const { options } = parseArgs(argv, {
    valueOptions: ["cwd", "pid-file", "endpoint"]
  });

  if (!options.endpoint) {
    throw new Error("Missing required --endpoint.");
  }

  const cwd = options.cwd ? path.resolve(process.cwd(), options.cwd) : process.cwd();
  const endpoint = String(options.endpoint);
  const listenTarget = parseBrokerEndpoint(endpoint);
  const pidFile = options["pid-file"] ? path.resolve(options["pid-file"]) : null;
  writePidFile(pidFile);

  const appClient = await CodexAppServerClient.connect(cwd, { disableBroker: true });
  let activeRequestSocket = null;

View on GitHub (pinned to db52e28f4d)

Solutions

1. Always invoke as: node scripts/app-server-broker.mjs serve --endpoint <value>
2. If calling from a wrapper, ensure 'serve' is the first element after the script path, before any flags.
3. Run with no args to reproduce, then add 'serve' as the explicit first positional.

Example fix

// before
node scripts/app-server-broker.mjs --endpoint unix:///tmp/broker.sock
// after
node scripts/app-server-broker.mjs serve --endpoint unix:///tmp/broker.sock

const sub = process.argv[2];
if (sub !== 'serve') {
  console.error('First arg must be "serve".');
  process.exit(2);
}

When it happens

Trigger: Running `node scripts/app-server-broker.mjs` with no arguments, with a typo'd subcommand like `start`, or with flags before the subcommand so parseArgs consumes 'serve'. The check is `subcommand !== 'serve'` so any other string (e.g. 'server', '--help') triggers it.

Common situations: Manual invocation for debugging where the developer forgets 'serve', copy-paste from docs that omit the subcommand, or an orchestration wrapper that passes flags in the wrong position so argv[2] is a flag instead of the literal 'serve'.

Related errors

• Missing required --endpoint.
• `/codex:review` now maps directly to the built-in reviewer a
• `status --wait` requires a job id.
• Unknown subcommand: ${subcommand}
• Missing version.\n\n${usage()}

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/e7edd9e4a1fa4d46. Report an issue: GitHub.