Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4133 pages
Next.js and React

Tailwind CSS 4 cannot load @tailwindcss/oxide or lightningcss for this platform

Your error

Error: Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.3 more lines it can show

Fix it fast

Most common cause, 1 of 3

Optional dependencies were skipped during install

Remove the omit setting and install again, keeping optional packages.

Fix
npm config delete omit
rm -rf node_modules
npm install
Did this fix it?
Full steps for this cause: check, fix, verify

Short answer

Tailwind CSS 4 runs native code from @tailwindcss/oxide and lightningcss, installed as optional packages built for one operating system and CPU. If the one for the current machine is missing, because optional packages were skipped, node_modules came from another OS, or the lockfile was made elsewhere, loading fails. Delete node_modules and package-lock.json and install again on the machine that runs the build.

  • Applies to tailwindcss 4.3, @tailwindcss/oxide 4.3.5, npm 11, Node.js 24, macOS arm64
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Which cause do you have?

See which platform packages are actually installed next to the main ones, and compare them with the machine you are on.

Run this first
node -p "process.platform + '-' + process.arch"
ls node_modules/@tailwindcss/ | grep oxide
ls node_modules | grep lightningcss

Then find the line you see in this list and open its fix:

  1. 1Optional dependencies were skipped during installOnly oxide and lightningcss are present, with no platform folder such as oxide-darwin-arm64 or lightningcss-darwin-arm64
  2. 2node_modules was copied from another operating systemWorks on the Mac, fails in a Linux container with a linux-*-gnu or linux-*-musl package name in the error
  3. 3The lockfile was written on another platformnpm ci on a CI runner or a teammate's machine fails even though nothing was copied by hand

What does the error look like?

  • Error: Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.
  • cause: Error: Cannot find module '@tailwindcss/oxide-darwin-arm64'
  • Error: Cannot find module '@tailwindcss/oxide-linux-arm64-gnu'
  • Error: Cannot find module '../lightningcss.darwin-arm64.node'

Cause 1 of 3

Optional dependencies were skipped during install

You seeOnly oxide and lightningcss are present, with no platform folder such as oxide-darwin-arm64 or lightningcss-darwin-arm64

Check

The platform builds are optional dependencies. Installing with --omit=optional, or with omit=optional in an .npmrc, leaves them out; the first module to load then fails, which is often lightningcss rather than oxide.

Check
npm config get omit
grep -n omit .npmrc ~/.npmrc 2>/dev/null

Fix

Remove the omit setting and install again, keeping optional packages.

Fix
npm config delete omit
rm -rf node_modules
npm install

Verify

The build writes CSS that contains your utility classes.

Verify
npx @tailwindcss/cli -i ./src/input.css -o ./dist/out.css && grep -c text-red-500 dist/out.css

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

node_modules was copied from another operating system

You seeWorks on the Mac, fails in a Linux container with a linux-*-gnu or linux-*-musl package name in the error

Check

A COPY . . without a .dockerignore brings the host's node_modules into the image. Those folders hold the macOS build of oxide, not the Linux one the container needs.

Check
cat .dockerignore 2>/dev/null | grep -n node_modules || echo "node_modules is not ignored"

Fix

Keep node_modules out of the build context and install inside the image, from package.json and the lockfile only.

Fix
# .dockerignore
node_modules
dist

# Dockerfile
FROM node:24-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

Verify

docker build passes the CSS build step, and the image contains the Linux oxide package.

Verify
docker run --rm <image> ls node_modules/@tailwindcss | grep oxide-linux

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The lockfile was written on another platform

You seenpm ci on a CI runner or a teammate's machine fails even though nothing was copied by hand

Check

The error text itself names npm issue 4828: platform-specific optional packages can be missing from package-lock.json when the lockfile is regenerated with node_modules present. The package for the other platform then never installs.

Check
grep -c '"node_modules/@tailwindcss/oxide-' package-lock.json

Fix

Follow the message: remove both node_modules and package-lock.json, install once, and commit the new lockfile.

Fix
rm -rf node_modules package-lock.json
npm install
git add package-lock.json && git commit -m "Regenerate lockfile with all oxide platforms"

Verify

The new lockfile lists oxide entries for several platforms, and CI installs and builds.

Verify
grep -o '"node_modules/@tailwindcss/oxide-[a-z0-9-]*"' package-lock.json | sort -u

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Never commit or copy node_modules between machines; install where the code runs.
  • Add node_modules to .dockerignore in every Node.js project.
  • Do not set omit=optional for projects that use native-binary tools such as Tailwind 4, esbuild or lightningcss.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.