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 ```