Next.js "next build" Fails with "Type error" - Fix in CI

By Kaveh Alemi·Latchkey

By default next build runs a full TypeScript type-check. The dev server uses fast transpile-only compilation that skips many checks, so a real type error sails through next dev and only fails when CI runs next build.

What this error means

The build stops with Failed to compile. and a Type error: naming a file, line, and the TS diagnostic. It is deterministic; the same code fails identically every run.

Failed to compile.

./app/cart/page.tsx:18:24
Type error: Argument of type 'string' is not assignable to parameter of type 'number'.

  16 |   const total = useCartTotal()
> 18 |   addToCart(productId)
     |             ^^^^^^^^^

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

Common causes

A real type error dev did not surface

next dev transpiles without full type-checking, so genuine mismatches only appear under next build. CI is the first place the full check runs.

Stricter types after a dependency bump

Updated @types/* or a library upgrade narrowed a signature, so code that previously compiled now errors during the build.

How to fix it

Fix the underlying type error

Reproduce the exact check the build runs, then correct the code at the named line.

npx tsc --noEmit   # same type-check next build runs
# fix the reported mismatch, e.g.
# addToCart(Number(productId))

Type-check before build in CI

Run the type-check as its own step so failures are clearly attributed.

- run: npx tsc --noEmit
- run: npm run build

Make the build reproducible before you debug it

• Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
• Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
• Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
• Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

How to prevent it

• Run tsc --noEmit locally and in CI before next build.
• Keep @types/* and libraries upgraded together so signatures stay aligned.
• Avoid ignoreBuildErrors; treat the build type-check as a required gate.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation