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

> Learn what happens when the Codex binary is not found or fails to start. The plugin aborts with installation instructions for a seamless recovery.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: troubleshooting
- Published: 2026-07-05

---

**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:

```javascript
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:

```javascript
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.