Troubleshooting

Reference intermediate

Common Codex CLI Problems and Solutions

Problem: Codex Cannot Access Network Resources

Symptoms: Codex fails when trying to install packages, fetch APIs, or download dependencies during execution.

Cause: The sandbox blocks outbound network access by default for security.

Solution:

  • Pre-install all dependencies before running Codex: npm install
  • Use --approval-policy never --sandbox danger-full-access with network access enabled if your task requires it
  • Mock external API calls in tests rather than making real requests
  • Include necessary packages in your package.json before starting
  • For documentation lookups, paste relevant docs into the prompt

Problem: AGENTS.md Is Being Ignored

Symptoms: Codex does not follow project conventions or instructions specified in AGENTS.md.

Cause: File is in the wrong location, has formatting issues, or is too large.

Solution:

  • Verify the file is named exactly AGENTS.md (case-sensitive)
  • Place it in the project root (same directory you run codex from)
  • Keep it under 4000 tokens (roughly 500 lines)
  • Use clear markdown headers for structure
  • Test by asking: "What are the project rules from AGENTS.md?"
  • Ensure the file is not in .gitignore (Codex may skip ignored files)

Problem: Codex Makes Changes to Wrong Files

Symptoms: Modifications appear in files you did not intend to change, or the wrong implementation file is edited.

Cause: Ambiguous prompt; multiple files match the description.

Solution:

  • Always specify exact file paths: "Fix the bug in src/lib/auth/validate.ts"
  • Add scope constraints: "Only modify files in src/features/auth/"
  • Use untrusted policy first to review the plan before applying
  • Add to AGENTS.md: "Never modify: [list of protected files]"

Problem: Sandbox Cannot Run Project Scripts

Symptoms: Error messages like "command not found" for project tooling (jest, vitest, tsc, eslint).

Cause: Node modules or tooling not available in the sandbox environment.

Solution:

  • Run npm install (or pnpm install) before starting Codex
  • Ensure node_modules/.bin is accessible
  • Specify in AGENTS.md which commands are available:
    # Available Commands
- npm test (runs vitest)
- npm run lint (runs eslint)
- npm run build (runs tsc)
  • Use npx for tools: "Run tests with npx vitest run"

Problem: Codex Produces Incomplete Code

Symptoms: Generated code has TODO comments, placeholder implementations, or cuts off mid-function.

Cause: Prompt is too broad for a single pass; model hit output limits.

Solution:

  • Break large tasks into smaller, focused prompts
  • Be specific about completeness: "Fully implement all functions, no TODOs"
  • Use iterative prompting: complete one file/function at a time
  • If code is cut off, follow up: "Continue the implementation from where you stopped"

Problem: Full-Auto Mode Makes Risky Changes

Symptoms: In --approval-policy never --sandbox danger-full-access, Codex deletes files, changes configs, or modifies sensitive code without approval.

Cause: Full-auto mode applies all changes without human review.

Solution:

  • Start in untrusted policy until you trust Codex with the task type
  • Add safeguards in AGENTS.md:
    # Never modify these files in any mode:
- .env, .env.*
- database/migrations/
- package.json (dependencies section)
- CI/CD configuration files
  • Use --approval-policy on-request (reviews before commit) instead of --approval-policy never --sandbox danger-full-access
  • Review git history after full-auto sessions: git log --oneline -10

Problem: Authentication/API Key Errors

Symptoms: "Invalid API key", "Unauthorized", or "Rate limit exceeded" errors.

Cause: Authentication not configured, session expired, or quota exhausted.

Solution:

  • If using ChatGPT auth: re-run codex auth login to refresh your session
  • If using API key: verify it's set: echo $CODEX_API_KEY | head -c 10
  • Check key validity at platform.openai.com
  • Ensure your ChatGPT plan includes Codex access (Plus, Pro, Business, Edu, Enterprise)
  • Check rate limits and usage quota
  • For API key auth, set in shell profile for persistence:
    # Add to ~/.zshrc or ~/.bashrc
export CODEX_API_KEY="sk-..."

Problem: Codex Suggests Outdated Patterns

Symptoms: Generated code uses deprecated APIs, old syntax, or unmaintained libraries.

Cause: Model training data has a knowledge cutoff.

Solution:

  • Specify exact versions in AGENTS.md and in your prompt
  • Paste relevant current documentation when using new APIs
  • Add negative constraints: "Do NOT use [deprecated pattern], use [current pattern]"
  • Include example code showing the modern approach you want
  • Reference your package.json versions explicitly

Problem: Changes Break Existing Tests

Symptoms: Codex's modifications cause previously passing tests to fail.

Cause: Codex does not always run the full test suite to verify no regressions.

Solution:

  • Add to AGENTS.md: "Always run npm test after making changes"
  • Include in prompt: "Ensure all existing tests still pass"
  • Use the test-driven fix pattern: write the test first, then implement
  • After Codex finishes, manually run: npm test to verify
  • Use --approval-policy on-request so you can check tests before committing

Problem: Codex Gives Up Too Easily

Symptoms: Response says "I cannot do this" or "this is too complex" for tasks that should be feasible.

Cause: Task is ambiguous or too large for the model to plan in one step.

Solution:

  • Decompose the task: "Let's start with step 1: [specific sub-task]"
  • Provide more context: paste relevant code, types, examples
  • Lower the scope: "Just handle the happy path first, we'll add error handling next"
  • Try a more capable model: codex --model gpt-5.5 "..."
  • Rephrase as concrete instructions rather than open-ended requests