bug: Cannot find native binding @astrojs/compiler-binding-linux-x64-gnu when running astro dev with pnpm #23

New Issue

2026-08-14T13:35:36Z

Ninosaurier commented

2026-08-14 13:35:36 +00:00

Description

When trying to run the development server via pnpm run docs (which triggers astro dev) inside a monorepo/workspace, the build fails with a missing native binding error.

Even though the console output references an outdated npm/cli issue (#4828) regarding optional dependencies, the project is strictly managed via pnpm. The root cause is tied to how pnpm resolves the supportedArchitectures config within a pnpm-workspace.yaml layout when filtering for specific environment matrices.

Error Output / Stack Trace

Cannot find native binding. npm has a bug related to optional dependencies (https://github.com). Please try `npm i` again after removing both package-lock.json and node_modules directory.
  Stack trace:
    at file:///home/onin/workspaces/BytingNinjaPandas/LUNA-Charts/node_modules/.pnpm/@astrojs+compiler-binding@0.3.2_@emnapi+core@2.0.0-alpha.3_@emnapi+runtime@2.0.0-alpha.3/node_modules/@astrojs/compiler-binding/index.js:575:11
  Caused by:
  Cannot find module '@astrojs/compiler-binding-linux-x64-gnu'

Environment

OS: Linux (x64 GNU) / Workspace path: /home/onin/workspaces/...
Package Manager: pnpm (v11+)
Astro Version/Compiler: @astrojs/compiler-binding@0.3.2 (Astro core ~7.1.6)

Steps to Reproduce

Set up a multi-package repository using pnpm-workspace.yaml.
Restrict architectures in pnpm-workspace.yaml using supportedArchitectures but omit explicit gnu libc entries (e.g., using only current and glibc).
Run pnpm install in an environment that shares state, runs inside WSL/Docker, or after clearing the global store cache via pnpm store prune.
Execute pnpm run docs or pnpm --filter docs run dev.
The compiler crashes instantly with ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL because the platform-specific binary is entirely skipped during installation.

Expected Behavior

pnpm should resolve and fetch the correct native binding platform package (@astrojs/compiler-binding-linux-x64-gnu) automatically based on the targeted platform requirements of the compiler dependency.

Actual Behavior

The native binary is skipped or missing in the local .pnpm store structure due to aggressive/strict architectural filtering rules applied at the workspace level, causing node to throw a Cannot find module error.

Workaround & Resolution

The issue can be temporarily bypassed by forcing the installation of the native binding directly into the devDependencies:

pnpm add -D @astrojs/compiler-binding-linux-x64-gnu

Permanent Workspace Fix:
The underlying cause is that pnpm requires an explicit gnu target entry inside the libc array of the pnpm-workspace.yaml configuration to allow the Astro GNU compiler binary to bypass the workspace filter:

supportedArchitectures:
  os:
    - current
    - linux
  cpu:
    - current
    - x64
  libc:
    - current
    - glibc
    - gnu  # <-- This missing entry fixes the issue

## Description When trying to run the development server via `pnpm run docs` (which triggers `astro dev`) inside a monorepo/workspace, the build fails with a missing native binding error. Even though the console output references an outdated `npm/cli` issue (#4828) regarding optional dependencies, the project is strictly managed via `pnpm`. The root cause is tied to how `pnpm` resolves the `supportedArchitectures` config within a `pnpm-workspace.yaml` layout when filtering for specific environment matrices. ## Error Output / Stack Trace ```text Cannot find native binding. npm has a bug related to optional dependencies (https://github.com). Please try `npm i` again after removing both package-lock.json and node_modules directory. Stack trace: at file:///home/onin/workspaces/BytingNinjaPandas/LUNA-Charts/node_modules/.pnpm/@astrojs+compiler-binding@0.3.2_@emnapi+core@2.0.0-alpha.3_@emnapi+runtime@2.0.0-alpha.3/node_modules/@astrojs/compiler-binding/index.js:575:11 Caused by: Cannot find module '@astrojs/compiler-binding-linux-x64-gnu' ``` ## Environment * **OS:** Linux (x64 GNU) / Workspace path: `/home/onin/workspaces/...` * **Package Manager:** `pnpm` (v11+) * **Astro Version/Compiler:** `@astrojs/compiler-binding@0.3.2` (Astro core `~7.1.6`) ## Steps to Reproduce 1. Set up a multi-package repository using `pnpm-workspace.yaml`. 2. Restrict architectures in `pnpm-workspace.yaml` using `supportedArchitectures` but omit explicit `gnu` libc entries (e.g., using only `current` and `glibc`). 3. Run `pnpm install` in an environment that shares state, runs inside WSL/Docker, or after clearing the global store cache via `pnpm store prune`. 4. Execute `pnpm run docs` or `pnpm --filter docs run dev`. 5. The compiler crashes instantly with `ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL` because the platform-specific binary is entirely skipped during installation. ## Expected Behavior `pnpm` should resolve and fetch the correct native binding platform package (`@astrojs/compiler-binding-linux-x64-gnu`) automatically based on the targeted platform requirements of the compiler dependency. ## Actual Behavior The native binary is skipped or missing in the local `.pnpm` store structure due to aggressive/strict architectural filtering rules applied at the workspace level, causing node to throw a `Cannot find module` error. ## Workaround & Resolution The issue can be temporarily bypassed by forcing the installation of the native binding directly into the devDependencies: ```bash pnpm add -D @astrojs/compiler-binding-linux-x64-gnu ``` **Permanent Workspace Fix:** The underlying cause is that `pnpm` requires an explicit `gnu` target entry inside the `libc` array of the `pnpm-workspace.yaml` configuration to allow the Astro GNU compiler binary to bypass the workspace filter: ```yaml supportedArchitectures: os: - current - linux cpu: - current - x64 libc: - current - glibc - gnu # <-- This missing entry fixes the issue ```

Ninosaurier added the Kind/Bug Priority/High Community/Good First Issue labels 2026-08-14 13:35:36 +00:00

Ninosaurier self-assigned this 2026-08-14 13:36:29 +00:00

Ninosaurier added the Status/Verified label 2026-08-14 13:36:44 +00:00

Ninosaurier referenced this issue from a commit

2026-08-15 19:34:38 +00:00

fix(docs): resolve missing native Astro compiler bindings in root execution

Ninosaurier referenced a pull request that will close this issue

2026-08-16 07:25:13 +00:00

fix(docs): resolve missing native Astro compiler bindings in root execution #24

Ninosaurier closed this issue

2026-08-16 07:28:46 +00:00

Ninosaurier referenced this issue from a commit

2026-08-16 07:28:46 +00:00

Merge pull request 'fix(docs): resolve missing native Astro compiler bindings in root execution' (#24) from fix/#23-astro-compiler-pnpm-linux-binary into dev

Ninosaurier commented

2026-08-19 06:53:51 +00:00

Reopened, because PR was only merged into dev.

Ninosaurier reopened this issue

2026-08-19 06:53:51 +00:00

Ninosaurier removed the Community/Good First Issue label 2026-08-20 15:45:44 +00:00

Ninosaurier commented

2026-08-26 12:24:02 +00:00

I hit the exact same error (Cannot find module '@astrojs/compiler-binding-linux-x64-gnu') on Astro 7 and wanted to share our findings, since it took a lot of digging to rule out everything else.

Environment: Linux x64 (Arch), Node 22.13, pnpm 11.11.0, monorepo workspace with supportedArchitectures configured for cross-platform lockfile support.

What we ruled out, in case it saves someone else time:

pnpm store corruption / hardlinks (packageImportMethod: copy had no effect)
Stale/skipped resolution (reproduced even after a fully fresh pnpm install with the lockfile deleted and the store wiped)

In every case, @astrojs/compiler-binding-linux-x64-gnu was never even attempted — not fetched, not linked, not mentioned anywhere in a verbose install log. Only pnpm install --force (which bypasses platform filtering entirely) produced a working install, which isn't something you can reasonably tell every dev/CI runner to rely on.

I eventually found this thread mentioning the exact same Cannot find native binding error in a different context, which was the hint that pointed us away from our own tooling and toward the package itself: issues15948.

Given that, our conclusion is that optionalDependencies-based distribution of the native binary in @astrojs/compiler-rs / @astrojs/compiler-binding is still fragile in some environments (at least Linux x64 + pnpm), independent of package manager config.

Our workaround: downgraded to astro@^6.3.0 + @astrojs/starlight@^0.40.0 (Starlight 0.41 dropped Astro 6 support) and removed @astrojs/compiler-binding as a direct dependency, since the legacy Go compiler doesn't need it. That's stable for us, but obviously not a real fix — happy to help repro if it's useful for narrowing this down further.

I hit the exact same error (Cannot find module '@astrojs/compiler-binding-linux-x64-gnu') on Astro 7 and wanted to share our findings, since it took a lot of digging to rule out everything else. Environment: Linux x64 (Arch), Node 22.13, pnpm 11.11.0, monorepo workspace with supportedArchitectures configured for cross-platform lockfile support. What we ruled out, in case it saves someone else time: pnpm store corruption / hardlinks (packageImportMethod: copy had no effect) Stale/skipped resolution (reproduced even after a fully fresh pnpm install with the lockfile deleted and the store wiped) In every case, @astrojs/compiler-binding-linux-x64-gnu was never even attempted — not fetched, not linked, not mentioned anywhere in a verbose install log. Only pnpm install --force (which bypasses platform filtering entirely) produced a working install, which isn't something you can reasonably tell every dev/CI runner to rely on. I eventually found this thread mentioning the exact same Cannot find native binding error in a different context, which was the hint that pointed us away from our own tooling and toward the package itself: [issues15948](https://github.com/withastro/astro/issues/15948). Given that, our conclusion is that optionalDependencies-based distribution of the native binary in @astrojs/compiler-rs / @astrojs/compiler-binding is still fragile in some environments (at least Linux x64 + pnpm), independent of package manager config. Our workaround: downgraded to astro@^6.3.0 + @astrojs/starlight@^0.40.0 (Starlight 0.41 dropped Astro 6 support) and removed @astrojs/compiler-binding as a direct dependency, since the legacy Go compiler doesn't need it. That's stable for us, but obviously not a real fix — happy to help repro if it's useful for narrowing this down further.

Ninosaurier added reference fix/#23-astro-compiler-pnpm-linux-binary

2026-08-26 12:44:56 +00:00

Ninosaurier commented

2026-08-26 12:59:25 +00:00

Hi @svki0001

I have updated the dependencies. Could you please test it on your end?

Branch: fix/#23-astro-compiler-pnpm-linux-binary
Run: pnpm install

Let me know if everything works fine!

Hi @svki0001 I have updated the dependencies. Could you please test it on your end? Branch: `fix/#23-astro-compiler-pnpm-linux-binary` Run: `pnpm install` Let me know if everything works fine!

👍 1

sven commented

2026-08-26 14:25:31 +00:00

Worked on my M2 Mac now.

Ninosaurier commented

2026-08-26 18:02:25 +00:00

Confirmed working cross-platform — thanks @sven for testing on M2 Mac, verified here on Linux x64/Arch too.

Root cause: @astrojs/compiler-rs/@astrojs/compiler-binding (Astro 7's mandatory Rust compiler) has fragile optionalDependencies-based native binary distribution. The Linux x64 gnu variant was never fetched during a normal pnpm install — ruled out store, resolution, and libc issues on our side; only --force worked, which isn't a viable standing requirement.

Fix on fix/#23-astro-compiler-pnpm-linux-binary:

Downgraded astro → ^6.3.0 (legacy Go compiler, no native binary needed)
Downgraded @astrojs/starlight → ^0.40.0 (0.41+ dropped Astro 6 support)
Removed @astrojs/compiler-binding from docs/package.json
Cleaned up now-dead pnpm-workspace.yaml entries

This is a workaround, not a permanent fix — staying off Astro 7 until this stabilizes upstream.

Confirmed working cross-platform — thanks @sven for testing on M2 Mac, verified here on Linux x64/Arch too. Root cause: @astrojs/compiler-rs/@astrojs/compiler-binding (Astro 7's mandatory Rust compiler) has fragile optionalDependencies-based native binary distribution. The Linux x64 gnu variant was never fetched during a normal pnpm install — ruled out store, resolution, and libc issues on our side; only --force worked, which isn't a viable standing requirement. Fix on fix/#23-astro-compiler-pnpm-linux-binary: Downgraded astro → ^6.3.0 (legacy Go compiler, no native binary needed) Downgraded @astrojs/starlight → ^0.40.0 (0.41+ dropped Astro 6 support) Removed @astrojs/compiler-binding from docs/package.json Cleaned up now-dead pnpm-workspace.yaml entries This is a workaround, not a permanent fix — staying off Astro 7 until this stabilizes upstream.

Ninosaurier closed this issue

2026-08-26 18:02:25 +00:00

Ninosaurier reopened this issue

2026-08-26 18:23:23 +00:00

Ninosaurier referenced this issue

2026-08-26 18:29:41 +00:00

Fix/#23 astro compiler pnpm linux binary #25

Ninosaurier referenced this issue

2026-08-26 18:33:53 +00:00

tracking: Re-upgrade to Astro 7 once @astrojs/compiler-binding pnpm resolution is fixed upstream #26

Ninosaurier added the Status/Awaiting Release label 2026-08-26 18:42:20 +00:00

Ninosaurier referenced this issue