What Happens When the Codex Binary Is Not Found or Fails to Start

When the Codex CLI binary is missing or fails to launch, the openai/codex-plugin-cc plugin immediately aborts the operation and returns a descriptive error containing installation instructions rather than proceeding with a broken runtime.

The openai/codex-plugin-cc repository implements early validation checks to ensure the Codex binary is available before executing any CLI-dependent operations. Instead of allowing operations to proceed with a corrupted or missing runtime, the plugin validates binary availability at every entry point and surfaces clear, actionable messages to the user.

How the Plugin Detects a Missing or Failed Binary

The detection logic relies on two coordinated functions that verify the binary exists and can execute successfully. These checks run before any public API method attempts to spawn the Codex process.

The getCodexAvailability() Gatekeeper

In plugins/codex/scripts/lib/codex.mjs (lines 886-894), the getCodexAvailability() function serves as the primary validation entry point. It performs sequential checks to confirm both basic CLI functionality and advanced runtime support:

export function getCodexAvailability(cwd) {
  const versionStatus = binaryAvailable("codex", ["--version"], { cwd });
  if (!versionStatus.available) {
    return versionStatus;               // ❌ binary not found or cannot run
  }
  const appServerStatus = binaryAvailable("codex", ["app-server", "--help"], { cwd });
  if (!appServerStatus.available) {
    return {
      available: false,
      detail: `${versionStatus.detail}; advanced runtime unavailable: ${appServerStatus.detail}`
    };
  }
  return {
    available: true,
    detail: `${versionStatus.detail}; advanced runtime available`
  };
}

This function first attempts to run codex --version to verify the binary exists and is executable. If that succeeds, it validates the advanced runtime by checking codex app-server --help. When either check fails, it returns an object with available: false and a detailed error message explaining what went wrong.

Low-Level binaryAvailable() Validation

The underlying validation occurs in plugins/codex/scripts/lib/process.mjs, where the binaryAvailable() helper executes the requested command using spawnSync. This utility returns { available: false, detail: <error-message> } when:

• The spawn fails with error codes like ENOENT (file not found) or EACCES (permission denied)
• The process returns a non-zero exit status

This low-level gatekeeper ensures that any operation requiring the Codex CLI is blocked if the binary cannot be executed, regardless of whether the file exists on disk.

Error Handling in Public API Methods

All public entry points in the plugin call getCodexAvailability() before attempting to interact with the Codex binary. If the availability check fails, they throw descriptive exceptions that include remediation steps.

The following functions implement this guard clause:

• runAppServerReview() (lines 1004-1006 in codex.mjs)
• runAppServerTurn() (lines 1098-1100 in codex.mjs)
• importExternalAgentSession()

Each function checks the availability result and throws an error with the message:

Codex CLI is not installed or is missing required runtime support. Install it with `npm install -g @openai/codex`, then rerun `/codex:setup`.

This prevents the plugin from attempting to spawn non-existent processes or handling corrupted runtime states, ensuring users receive immediate feedback about installation issues.

Practical Example: Catching Binary Errors in Code

When integrating the Codex plugin into your workflow, you can catch these validation errors to handle missing binaries gracefully:

import { runAppServerTurn } from "./plugins/codex/scripts/lib/codex.mjs";

try {
  const result = await runAppServerTurn(process.cwd(), { prompt: "Fix the bug" });
  console.log("Turn completed:", result);
} catch (err) {
  // When the binary is missing the error message will contain installation instructions
  console.error("❗️ Codex error:", err.message);
}

If the codex binary cannot be executed, the catch block receives the detailed error message prompting the user to install the CLI globally and rerun the setup command.

Summary

• Early validation: The getCodexAvailability() function in plugins/codex/scripts/lib/codex.mjs checks binary status before any operations execute.
• Dual verification: The plugin validates both basic CLI functionality (--version) and advanced runtime support (app-server --help).
• Clear error messages: When the binary is missing or fails to start, users receive specific installation instructions rather than generic failure messages.
• Protected entry points: All public methods including runAppServerReview() and runAppServerTurn() abort immediately if the binary check fails.
• Low-level safety: The binaryAvailable() helper in plugins/codex/scripts/lib/process.mjs handles ENOENT, EACCES, and non-zero exit codes to catch every failure mode.

Frequently Asked Questions

How does the plugin verify that the Codex binary is installed?

The plugin uses getCodexAvailability() in plugins/codex/scripts/lib/codex.mjs to execute codex --version and codex app-server --help via the binaryAvailable() helper in plugins/codex/scripts/lib/process.mjs. If either command fails to spawn or returns a non-zero exit code, the binary is marked as unavailable.

What error message appears when the Codex binary is not found?

When the binary is missing or fails to start, the plugin throws an error stating: "Codex CLI is not installed or is missing required runtime support. Install it with npm install -g @openai/codex, then rerun /codex:setup." This message appears in the detail property of the availability check result.

Which API functions check for binary availability before executing?

runAppServerReview(), runAppServerTurn(), and importExternalAgentSession() all call getCodexAvailability() at the start of their execution flow (lines 1004-1006 and 1098-1100 in codex.mjs). If the check fails, these functions throw immediately without attempting to spawn the Codex process.

Where is the binary availability check implemented in the source code?

The primary check logic resides in plugins/codex/scripts/lib/codex.mjs (lines 886-894), while the low-level process spawning validation is implemented in plugins/codex/scripts/lib/process.mjs. Additional related files include plugins/codex/scripts/lib/app-server.mjs and plugins/codex/scripts/lib/broker-lifecycle.mjs, which rely on these checks before initializing connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}