Parcel "Build failed. @parcel/core" - Diagnose Parcel Errors in CI

By Kaveh Alemi·Latchkey

Parcel's @parcel/core aborts with "Build failed." and a specific diagnostic - a module it could not resolve, a transformer that threw, or a config it could not load. The real cause is in the diagnostic block, not the headline.

What this error means

A parcel build fails with 🚨 Build failed. and a @parcel/core (or @parcel/transformer-*) diagnostic naming a file and reason. It often passes locally where a stale cache hid the problem.

🚨 Build failed.
@parcel/core: Failed to resolve 'react-dom/client' from './src/index.tsx'
  /app/src/index.tsx:2:28
    1 | import { createRoot } from 'react-dom/client'

Common causes

Missing dependency or wrong path

A package or subpath Parcel cannot resolve - not installed, or a path/extension the resolver does not find on a clean install.

Transformer/plugin failure

A @parcel/transformer-* or community plugin throws on a file it cannot process, or a .parcelrc references a plugin that is not installed.

Stale .parcel-cache

A cached build in .parcel-cache masked a change locally; CI builds clean and surfaces the real failure.

How to fix it

Read the diagnostic and install/fix what it names

1. Read the @parcel/core diagnostic - it names the file, line, and reason.
2. Install the missing dependency or correct the path it reports.
3. Ensure every plugin referenced in .parcelrc is in devDependencies.

Clear the Parcel cache to match CI

Reproduce the clean build locally by removing the cache and build output.

rm -rf .parcel-cache dist
npx parcel build src/index.html

How to prevent it

• Declare all dependencies and .parcelrc plugins; install with npm ci.
• Clear .parcel-cache when reproducing CI build failures.
• Run parcel build in CI so transformer/resolver gaps surface early.

Frequently asked questions

Related guides

References

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