Bug Fixing

Codex is especially effective at fixing bugs when you provide clear reproduction steps, constraints, and a way to verify the fix. This workflow shows you how to set Codex up for success on bug fixes of any complexity.

The Formula#

The best bug fix prompts follow this structure:

Bug: [What is wrong]
Steps to reproduce: [How to trigger it]
Expected behavior: [What should happen]
Constraints: [What NOT to change]
Verification: [How to confirm the fix]

Simple Bug Fix#

For straightforward bugs with clear errors:

codex "The login form throws a TypeError when the email field is empty.
Steps to reproduce:
1. Go to /login
2. Leave email blank, enter a password
3. Click Submit

Fix the bug. The fix should handle empty email gracefully
with a validation message. Run the existing tests after fixing."

Complex Bug Fix#

For multi-file issues or intermittent bugs:

codex "Users report that their cart totals are sometimes wrong.
After investigation, the issue appears when items have discounts.

Context:
- Cart logic is in src/lib/cart.ts
- Discount logic is in src/lib/pricing.ts
- The bug seems related to percentage vs fixed discounts being mixed

Constraints:
- Do not change the discount data model
- Do not modify the database schema
- Keep backward compatibility with existing cart data

Fix the calculation bug and add test cases covering:
1. Percentage discount only
2. Fixed discount only
3. Mixed percentage and fixed discounts
4. Zero-value discounts
5. Discounts exceeding item price"

Using Error Messages#

Paste error messages directly into your prompt:

codex "Fix this error that occurs when processing payments:

\`\`\`
TypeError: Cannot read properties of undefined (reading 'amount')
    at processPayment (src/services/payment.ts:42:18)
    at async handleCheckout (src/api/checkout.ts:15:5)
\`\`\`

The error happens when a user checks out with a saved payment method.
New payment methods work fine."

## Workflow with Verification

The strongest bug fix workflow includes automatic verification:

Step 1: Reproduce (Optional but Recommended)#

codex "Can you find and run the existing test that covers the
checkout flow? I want to see if it already catches this bug."

Step 2: Fix and Test#

codex "Fix the TypeError in processPayment. After fixing:
1. Run the existing test suite
2. Add a new test case for saved payment methods
3. Verify all tests pass"

Step 3: Review#

Use /review to check the changes before committing:

/review
# Select "Review uncommitted changes"

Step 4: Verify Manually#

After Codex fixes the code, manually test the scenario to confirm.

CI/CD Auto-Fix#

Automate bug fixing when CI fails:

# In your CI pipeline
codex exec "The test suite failed with the following errors:
$(cat test-output.log | tail -50)

Fix the failing tests. Do not skip or delete tests.
Run the full test suite after fixing."

Tips for Better Bug Fixes#

1. Be specific about what is wrong — "Login is broken" is worse than "Login returns 500 when email contains a + character"
2. Include reproduction steps — Numbered steps that reliably trigger the bug
3. Set constraints — Tell Codex what NOT to change (e.g., "do not modify the API contract")
4. Provide test data — Include sample inputs that trigger the bug
5. Ask for tests — Request test cases alongside the fix to prevent regressions

## Next Steps

• UI Prototyping — Build UI from designs
• Code Review — Review fixes before merging
• Non-Interactive Mode — Automate fixes in CI