Codex Stalls on a Merge Conflict or Resolves It the Wrong Way
Codex hits conflict markers and either stops, picks the wrong side, or hand-edits the markers into the file. Pre-rebase setup.sh and explicit AGENTS.md rules fix it.
🛠️ Codex & Coding Agent Issues
Codex ignores structure, can`t finish patches, duplicates files, misreads builds, unsafe assumptions, shallow review, generic tests, patch conflicts, style drift, broad audits.
Codex is a sandboxed cloud agent — great for running tasks independently without burning local session, but it`s also the easiest place to ship "functionally correct, structurally wrong" code: wrong directories, v2 file duplicates, tests that ignore conventions, 50-bullet audits no one can act on. This hub breaks down real Codex failure modes: one symptom per article, with `AGENTS.md` patterns and verification steps. For developers who actually integrate Codex into their workflow, not just demo it.
Common problems
- Codex ignores your project structure AGENTS.md with directory tree + package boundaries.
- Codex cannot finish a patch cleanly Done = typecheck + test + lint all pass.
- Codex duplicates files instead of editing existing ones Ban `*-v2`, `*-new` files — edit in place.
- Codex fails to run or interpret build results Short parseable output + trust exit codes only.
- Codex makes unsafe assumptions Quote-before-write rule.
- Codex code review quality feels shallow Focused questions + require file:line citations.
- Codex test suggestions are too generic Bind to real signatures + bug regression coverage.
- Codex patch conflicts with existing code Re-read + regenerate patch — never force-apply stale hunks.
- Codex fixes one bug but breaks nearby logic Cap blast radius + enumerate callers before shared changes.
- Codex misses project-specific conventions Every AGENTS.md rule pairs with a canonical example.
- Codex audit report is too broad to act on Narrow dimension + cap N items + demand file:line.
- Codex-generated code does not fit the existing style Canonical example file + prettier + lint as backstop.
- Codex output does not fit the project Constrain style with AGENTS.md and explicit file refs.
- Codex cannot access a private repo Install GitHub App on target org + select the repo.
- Codex environment setup fails Pin versions (.nvmrc / .python-version) + inject tokens.
- Codex PR too large to merge Split into 3-5 small tasks; AGENTS.md: ≤ 200 lines per PR.
In-depth articles in this hub
Codex Added a Package but the Lockfile Did Not Change
Codex edits package.json but never ran npm install, so package-lock.json diverges. How to enforce lockfile updates via setup.sh, CI, and AGENTS.md.
Codex Creates a New TypeScript Interface Duplicating One That Already Exists
Codex defines a fresh User or ApiResponse type when an identical one lives elsewhere. How to make the agent search first via AGENTS.md, indexes, and ts-morph.
Codex Amended or Rebased Git History You Did Not Want Touched
Codex ran git commit --amend or interactive rebase from an old README, rewriting shared history. How to lock the agent to forward-only commits.
Codex PR Description Says "Refactored Components" and Nothing Else
Codex emits a one-line PR body with no detail. How to force a structured description with before/after, why, and test plan via templates and AGENTS.md.
Codex Says Tests Passed but Actually Skipped the Failures
Codex reports green tests but the failing cases were filtered out, marked .skip, or bailed early. How to force honest test reporting before merge.
Codex Bails Out When the Patch Gets Too Large
Codex hits a context or token cap mid-task and stops with a partial diff. How to scope tasks smaller, split across PRs, or move to a larger-context model.
Codex Writes React.FC, componentWillMount, and Other Deprecated APIs
Codex outputs API patterns deprecated years ago because its training data is dated. How to lock it to modern APIs via AGENTS.md, ESLint deprecation rules, and reference docs.
Codex Committed Your Work to the Wrong Branch (or Straight to main)
Codex ran git commit on whatever branch was checked out — sometimes main, sometimes a leftover branch from the previous task. How to force a clean per-task branch.
Codex's Fix Passes Every Test but Breaks at Runtime
Codex's PR is green in CI — every test passes — but the app crashes in staging. Why agent fixes that target the test surface miss the runtime, and how to close the gap.
Codex Agent Output Conflicts With Prettier
Codex writes a file, Prettier reformats it on save, and now the diff is huge. Fix by running Prettier inside the agent loop and aligning agent style hints to your .prettierrc.
Codex Agent Goes Out-of-Context on Long Repos
On 500k+ line codebases Codex loses track halfway. Fix by scoping the working set, using directory summaries, and forcing the agent to read AGENTS.md before scanning.
Codex Agent Skips Files Containing Binary Data
Codex silently skips PNGs, PDFs, sqlite DBs, compiled artifacts. The fix is allowlisting text extensions, hashing binaries instead of reading, and giving Codex a binary-aware tool.
Codex Agent Spawns Too Many Redundant Tool Calls
Codex re-reads the same file 8 times and re-greps the same query 5 times. Fix by pre-feeding context, requiring a plan first, and capping reads via tool restrictions.
Codex Agent Stops Mid-Task Without Error
Codex halts halfway through a multi-step task with no visible failure — usually a context window, sandbox timeout, or stop-condition issue. Diagnose by checking the last tool call and turn budget.