Troubleshooting

Common issues and how to resolve them.

When to use this page

  • You get an exception from acodex and want the next step.

  • The Codex CLI executable is not found or fails to run.

  • Structured output parsing/validation fails.

Executable not found

If you see CodexExecutableNotFoundError:

  • Ensure the Codex CLI is installed and codex is on PATH.

  • Or pass codex_path_override="/path/to/codex" to Codex(...) / AsyncCodex(...).

Structured output errors

If you see CodexStructuredResponseError when accessing turn.structured_response:

  • Ensure your prompt actually returns JSON matching the schema/model.

  • If using output_type, ensure you installed the extra: uv add "acodex[structured-output]" (or pip install "acodex[structured-output]").

Streamed result accessed too early

If you see CodexThreadStreamNotConsumedError:

  • Consume the full streamed.events iterator (or async iterator) before accessing streamed.result.