affaan-m/ECC · error · Error

Codex probe failed ` : ''}

Error message

Codex ${label} probe failed${detail ? `: ${detail}` : ''}

What it means

probeCodex wraps every `codex` CLI probe invocation. When the spawned process exits with a non-zero status code, this error is thrown with the last line of the CLI's stderr appended as detail (e.g. `Codex version probe failed: <stderr line>`). It signals that the Codex CLI itself rejected the probe command, so the tool-less review cannot proceed.

Solutions

  1. Run `codex --version` (and `codex features list`) manually in a terminal to see the full stderr and fix the underlying CLI failure
  2. Reinstall or update the Codex CLI to a known-good version (script pins codex-cli 0.146.0)
  3. Clear or repair CODEX_HOME configuration that may be crashing the CLI at startup
  4. Check that the sanitized environment (PATH, HOME, CODEX_HOME) passed to the probe still allows the CLI to run

Example fix

// before (old codex without subcommand)
$ codex features list
Unknown command: features
// after (upgrade Codex CLI)
npm install -g @openai/codex@0.146.0
$ codex features list   # exits 0
Defensive patterns

Strategy: try-catch

Validate before calling

const { execFileSync } = require('child_process');
function codexProbeWorks() {
  try {
    execFileSync('codex', ['--version'], { encoding: 'utf8', timeout: 5000 });
    return true;
  } catch (e) {
    return false;
  }
}

Type guard

function isSpawnOk(result) {
  return result != null && !result.error && result.status === 0;
}

Try / catch

try {
  const version = verifyToollessSupport();
} catch (err) {
  if (String(err.message).startsWith('Codex version probe failed')) {
    console.error('Codex CLI probe failed; reinstall or repair codex:', err.message);
  } else throw err;
}

Prevention

When it happens

Trigger: Calling verifyToollessSupport() which invokes probeCodex(spawn, ['--version'], ..., 'version') or probeCodex(spawn, ['features', 'list'], ..., 'feature'); the spawned `codex --version` or `codex features list` process returns a non-zero exit status.

Common situations: A broken or partially uninstalled Codex CLI; a Codex binary that fails on startup due to corrupt CODEX_HOME config; a version of codex-cli that does not support the `features list` subcommand; an authenticated/session error printed to stderr by the CLI.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

Thrown at skills/council-multi-model/scripts/review-with-codex.js:124

    '--color', 'never',
    '--config', 'shell_environment_policy.inherit="none"',
    '--config', 'skills.include_instructions=false',
    '--config', 'web_search="disabled"',
    '--config', 'mcp_servers={}',
    '--output-last-message', outputFile,
    '-',
  ];
}

function probeCodex(spawn, args, options, label) {
  const result = spawn('codex', args, options);
  if (result.error) {
    if (result.error.code === 'ENOENT') throw new Error('Codex CLI is not installed');
    throw new Error(`Codex ${label} probe failed: ${result.error.message}`);
  }
  if (result.status !== 0) {
    const detail = (result.stderr || '').trim().split('\n').slice(-1)[0];
    throw new Error(`Codex ${label} probe failed${detail ? `: ${detail}` : ''}`);
  }
  return (result.stdout || '').trim();
}

function verifyToollessSupport(dependencies = {}) {
  const spawn = dependencies.spawnSync || spawnSync;
  const options = {
    cwd: os.tmpdir(),
    env: buildEnvironment(dependencies.env || process.env),
    encoding: 'utf8',
    timeout: 5_000,
    maxBuffer: 256 * 1024,
    windowsHide: true,
  };
  const versionText = probeCodex(spawn, ['--version'], options, 'version');
  const versionMatch = versionText.match(/^codex-cli\s+([^\s]+)$/m);
  if (!versionMatch) {
    throw new Error('Codex version could not be verified for tool-less review');

View on GitHub (pinned to 8321021c54)