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.

next build output

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)
     |             ^^^^^^^^^

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.

Terminal

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.

.github/workflows/ci.yml

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

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

What causes ""Type error" (next build)"?

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

How do I fix "Type error" (next build)?