Error Handling Patterns for Failing Codex Commands in openai/codex-plugin-cc

When a Codex command fails, the openai/codex-plugin-cc repository validates prerequisites upfront, wraps external calls in try/catch blocks, sanitizes error messages through cleanCodexStderr, and reports them via the ProgressReporter callback before marking the TurnCaptureState as errored.

The openai/codex-plugin-cc repository implements a systematic architecture for error handling patterns for failing Codex commands. This design ensures that failures are detected early, logged consistently, and surfaced to users without leaving the runtime in an indeterminate state. The following patterns demonstrate how the codebase maintains safety and observability across asynchronous operations and external tool invocations.

Pre-Flight Validation and Guard-Rails

The plugin validates prerequisites before executing any external command. This fail-fast approach prevents unnecessary operations when required binaries or environment conditions are missing.

In /plugins/codex/scripts/lib/git.mjs, the code checks for binary availability and throws a descriptive error immediately if the dependency is absent:

// plugins/codex/scripts/lib/git.mjs
if (!binaryAvailable("git")) {
  throw new Error("git is not installed. Install Git and retry.");
}

This pattern ensures that users receive clear, actionable feedback before any asynchronous operations begin.

Wrapping External Calls in Try/Catch Blocks

Every async operation, Node child_process spawn, HTTP request, or file I/O call is enclosed in a try … catch construct. This pattern appears throughout /plugins/codex/scripts/lib/codex.mjs, where external tool executions are wrapped to intercept failures.

The standard pattern follows this sequence:

1. Execute the external call within a try block
2. Catch exceptions and clean stderr output using cleanCodexStderr
3. Emit the sanitized error via emitLogEvent
4. Update the TurnCaptureState to record the failure
5. Rethrow the exception to signal failure to upstream callers

// plugins/codex/scripts/lib/codex.mjs
try {
  const result = await someExternalTool(params);
  // …process result…
} catch (e) {
  // Clean up noisy stderr lines
  const clean = cleanCodexStderr(e.stderr || "");
  // Send a readable error to the UI
  emitLogEvent(onProgress, {
    message: clean || e.message,
    phase: "error",
    stderrMessage: clean,
  });
  // Record the error in the capture state and finish the turn
  state.error = e;
  completeTurn(state, null, { inferred: true });
  throw e; // re‑throw so callers know the operation failed
}

Normalizing and Surfacing Error Messages

Raw error output from external tools often contains noisy warnings or stack traces that confuse users. The plugin applies error normalization through the cleanCodexStderr function, which filters non-essential lines to produce concise, human-readable messages.

After sanitization, the emitLogEvent function forwards the cleaned message to the progress reporter:

function emitLogEvent(onProgress, { message, phase, stderrMessage }) {
  if (!onProgress) return;
  onProgress({ message, phase, stderrMessage, logTitle: "Codex Error" });
}

This ensures that UI components receive a structured payload containing the error message, phase identifier, and sanitized stderr content.

Progress Reporter Integration

The ProgressReporter callback serves as the central conduit for error visibility. When a command fails, the catch block invokes emitLogEvent with a payload object containing message, phase, and stderrMessage properties.

This integration allows the front-end to display user-friendly failure UI without parsing raw exception objects. The pattern is consistent across command execution, file-change handling, and tool call failures in /plugins/codex/scripts/lib/codex.mjs.

State Machine Updates for Failed Commands

To prevent the runtime from hanging while waiting for missing results, the plugin updates the internal TurnCaptureState immediately upon failure. The state.error property is set to the caught exception, and completeTurn is invoked to finalize the turn:

state.error = e;
completeTurn(state, null, { inferred: true });

This state transition ensures that the command lifecycle completes cleanly, even when the operation returns no valid result. The inferred: true flag indicates that the turn was completed automatically due to error conditions rather than successful inference.

User-Visible Fallbacks and Fail-Fast Contracts

When commands fail early—such as during the missing binary check in /plugins/codex/scripts/lib/git.mjs or process spawning in /plugins/codex/scripts/lib/process.mjs—the plugin aborts immediately and returns the error message directly to the user.

According to the command-level contract described in /plugins/codex/commands/review.md, the foreground flow returns stdout verbatim on success, but returns the caught exception message on failure. This preserves a consistent fail-fast contract where errors are never swallowed or converted into opaque error codes.

Summary

• Guard-rails validate prerequisites like binary availability before any external calls execute.
• Try/catch wrapping captures exceptions from async operations, file I/O, and child processes.
• Error normalization via cleanCodexStderr removes noise from stderr before display.
• Progress reporting through emitLogEvent sends structured error payloads to the UI.
• State machine updates mark TurnCaptureState as errored and complete the turn to prevent hangs.
• Fail-fast contracts return clear error messages directly to users rather than opaque codes.

Frequently Asked Questions

How does the plugin handle missing binary dependencies?

The plugin checks for required binaries using the binaryAvailable function before executing any external commands. In /plugins/codex/scripts/lib/git.mjs, if Git is not installed, the code throws new Error("git is not installed. Install Git and retry.") immediately, preventing subsequent operations from attempting to run.

What happens to the TurnCaptureState when a command fails?

When a command fails, the catch block assigns the exception to state.error and calls completeTurn(state, null, { inferred: true }). This marks the turn as completed with an error status, ensuring the runtime does not wait indefinitely for a result that will never arrive.

How are error messages sanitized before being displayed to users?

Raw stderr output is passed through cleanCodexStderr, which filters out noisy warnings and non-essential lines. The sanitized result is then sent via emitLogEvent to the ProgressReporter callback with a structured payload containing message, phase: "error", and stderrMessage properties.

Why does the plugin re-throw errors after catching and logging them?

After updating the state and emitting the progress event, the code executes throw e to propagate the exception up the call stack. This ensures that upstream callers recognize the operation failed while the lower layers have already handled logging, state updates, and user notification.

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