AI AI Tools Guidebook
Troubleshooting

AI Code Edits Broke the Build — Recovery + Diagnosis

After an AI run, npm run build fails. Diagnose with diff review, type-checking, and selective revert.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

You let Claude Code run a refactor for 30 minutes. You come back, run npm run build, and get a wall of red: Cannot find name 'XYZ', Module has no exported member 'foo', vite.config.ts:12 Unexpected token. The agent confidently reports “fixed and tested” — but the build never lies. “AI cleaned things up and now the build is broken” is one of the most common incidents in agent-assisted dev today. Most of the time it touched a config file it shouldn’t have, added a non-existent import, or left dev-time mocks behind. This article gives you a targeted-revert flow — no full reset, locate the bad change in 10 minutes.

Common causes

Ordered by hit rate, highest first.

1. Agent edited a config file (tsconfig / vite.config / next.config)

The most common and most painful. Agent sees a type error and loosens tsconfig.json strict, or rewrites resolve.alias in vite.config.ts — a single local fix cascades into a global build failure.

error TS5023: Unknown compiler option 'allowImportingTsExtensions'.
error during build:
RollupError: "default" is not exported by "src/utils/helpers"

How to spot it: git diff main -- '*.config.*' tsconfig*.json shows whether any config file was touched.

2. Imports that don’t resolve

Agent invents a utility path (@/utils/superhelper, ./lib/notFound), TypeScript can’t find it:

src/components/Form.tsx:5:18 - error TS2307: Cannot find module
  '@/utils/superhelper' or its corresponding type declarations.

How to spot it: tsc --noEmit lists every TS2307 / TS2305.

3. Test mocks left behind

Agent added vi.mock('next/router') during debugging or stuffed experimental: { mock: true } into next.config.js and forgot to remove it.

Error: <Link> requires an href prop

How to spot it: Grep the diff for mock, stub, fixture, TODO, XXX.

4. Deleted an export used by other files

Agent thought a function was unused and deleted it. 5 other files still import it:

src/pages/index.tsx:8:10 - error TS2305: Module './lib/auth'
  has no exported member 'verifyToken'.

How to spot it: has no exported member or cannot find name in the build error.

5. Incompatible package version (API breaking)

Agent bumped a major version (React 18 → 19, Next.js 14 → 15) but the code still uses the old API:

TypeError: ReactDOM.render is not a function

How to spot it: git diff main -- package.json for major version jumps.

6. ESM / CJS mismatch

Agent wrote require() in an ESM project or top-level import in a CJS project:

SyntaxError: Cannot use import statement outside a module

How to spot it: Check "type": "module" in package.json against the import/require syntax used.

Shortest path to fix

Ordered by ROI. Steps 1-3 locate 90% of failures.

Step 1: Stash first, keep a clean comparison point

Don’t touch code yet. Snapshot first:

git stash push -m "ai-broken-build-snapshot"   # save current state
git stash apply                                # re-apply, don't drop stash

You can always git stash pop back to the agent’s output. If the changes are already committed:

git tag broken-build-snapshot                   # tag current commit

Step 2: List changed files with git diff, sort by risk

git diff main --stat

Triage in this order (risk descending):

PriorityFile typeRisk
1tsconfig*.json *.config.{js,ts,mjs}One edit breaks everything
2package.json package-lock.jsonDep incompatibility
3src/lib/** src/utils/**Imported by many files
4src/components/**Bounded blast radius
5src/pages/** src/app/**Single page fails

Step 3: Run tsc --noEmit to surface every type error

Don’t go straight to npm run build — it stops at the first error. First:

npx tsc --noEmit | head -50

This lists every type error at once, so you can tell whether it’s one cascading change or several independent ones. If they all cluster on imports from one file, you’ve already located it.

Step 4: Selectively revert the high-risk files

Try reverting config files first:

git checkout main -- tsconfig.json vite.config.ts next.config.js
npm run build

If build passes, the issue was config. If it still fails, restore the config changes (git stash pop or re-apply) and revert the next group:

git checkout main -- src/lib/ src/utils/
npm run build

Bisecting beats full reset. Build after each revert group.

Step 5: Feed the root cause back into the agent

Once you know which files / lines broke things, don’t hand-fix — give the agent a precise prompt:

Your last change broke the build. Exact errors:
[paste full tsc --noEmit output]

Do only this:
1. Do not touch tsconfig.json / vite.config.ts.
2. Fix every type error above with the smallest possible edit per error.
3. Run tsc --noEmit until green before saying "done."

Explicitly forbidding config edits prevents the repeat.

Prevention

  • In CLAUDE.md / AGENTS.md / .cursorrules, explicitly forbid edits to config files. List exact paths: tsconfig.json, vite.config.*, next.config.*, astro.config.*, package.json (except for npm install)
  • Pre-commit hook runs tsc --noEmit and npm run build; failure blocks the commit
  • Require the agent to run npm run build (not just npm test) before declaring “done”
  • Break long refactors into small commits; each commit must build independently
  • Review config file changes separately — never bundle them in a feature PR
  • Use git worktree so the agent works in an isolated branch, main stays always-buildable

Tags: #AI coding #Debug #Troubleshooting

Related Articles