fix: use hardlink package-import-method so Docker build works on ZFS (#7342)#7533
Merged
JohnMcLear merged 1 commit intodevelopfrom Apr 17, 2026
Merged
fix: use hardlink package-import-method so Docker build works on ZFS (#7342)#7533JohnMcLear merged 1 commit intodevelopfrom
JohnMcLear merged 1 commit intodevelopfrom
Conversation
…ZFS (#7342) pnpm's default \`auto\` package-import-method eventually falls through to \`copyfile\`, which uses \`copy_file_range\`. That syscall fails on ZFS with \`EAGAIN: resource temporarily unavailable\` (see pnpm/pnpm#7024), so \`docker compose build\` aborts inside the \`RUN pnpm install\` step on any host with a ZFS root. Operators had to hand-patch every pnpm invocation in the Dockerfile and install scripts. Force \`package-import-method=hardlink\` in \`.npmrc\` so all pnpm invocations (Docker build, \`bin/installDeps.sh\`, \`bin/installLocalPlugins.sh\`, \`bin/updatePlugins.sh\`) pick up the setting automatically. Hardlinks are fast, save disk, and work on every filesystem Etherpad supports. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Review Summary by QodoConfigure pnpm hardlink package-import-method for ZFS compatibility
WalkthroughsDescription• Configure pnpm to use hardlinks for package imports • Resolves Docker build failures on ZFS filesystems • Eliminates need for per-command flag workarounds • Improves performance and disk usage across all pnpm invocations Diagramflowchart LR
A["pnpm default auto mode"] -->|"uses copy_file_range"| B["Fails on ZFS"]
B -->|"breaks docker build"| C["Build aborts"]
D[".npmrc configuration"] -->|"sets hardlink method"| E["All pnpm commands"]
E -->|"works on all filesystems"| F["Successful builds"]
File Changes1. .npmrc
|
Code Review by Qodo
1. ZFS pnpm hardlink untested
|
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Comment on lines
+2
to
+7
| # Use hardlinks when populating node_modules instead of clone/copyfile. | ||
| # pnpm's default "auto" mode ends up using copy_file_range which fails on | ||
| # ZFS (https://github.com/pnpm/pnpm/issues/7024) and breaks `docker | ||
| # compose build` on hosts with a ZFS root (#7342). Hardlinks are fast, | ||
| # save disk, and work on every filesystem Etherpad supports. | ||
| package-import-method=hardlink |
There was a problem hiding this comment.
1. Zfs pnpm hardlink untested 📘 Rule violation ☼ Reliability
This PR changes pnpm behavior to fix ZFS-related Docker build failures but does not add/update any regression test that would fail if the .npmrc setting were reverted. Without a test, the mitigation can silently regress and reintroduce the ZFS EAGAIN install failure.
Agent Prompt
## Issue description
A bug fix (pnpm ZFS mitigation via `.npmrc`) was added without a regression test, so reverting/removing the setting would not be caught by automated tests.
## Issue Context
The change introduces `package-import-method=hardlink` to prevent pnpm `EAGAIN` failures on ZFS during Docker builds.
## Fix Focus Areas
- .npmrc[2-7]
- src/tests/backend-new/specs/pnpm_import_method.test.ts[1-200]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+2
to
+7
| # Use hardlinks when populating node_modules instead of clone/copyfile. | ||
| # pnpm's default "auto" mode ends up using copy_file_range which fails on | ||
| # ZFS (https://github.com/pnpm/pnpm/issues/7024) and breaks `docker | ||
| # compose build` on hosts with a ZFS root (#7342). Hardlinks are fast, | ||
| # save disk, and work on every filesystem Etherpad supports. | ||
| package-import-method=hardlink |
There was a problem hiding this comment.
2. Docker ignores new pnpm config 🐞 Bug ≡ Correctness
The new package-import-method=hardlink setting is not applied to pnpm commands run by bin/installDeps.sh/bin/installLocalPlugins.sh during Docker builds because .npmrc is never copied into the relevant Docker build stages. This can leave Docker builds on ZFS still using pnpm’s default import method and failing despite this PR.
Agent Prompt
### Issue description
The PR relies on a repo-level `.npmrc` to force `package-import-method=hardlink`, but the Docker build stages that execute `bin/installDeps.sh` and `bin/installLocalPlugins.sh` do not include `.npmrc`. As a result, pnpm in those stages will not pick up the new config and can still fail on ZFS.
### Issue Context
- `.npmrc` is present in the repo and will be present in stages that `COPY . .`, but the main `build` stage uses selective `COPY` instructions and omits `.npmrc`.
- The Dockerfile later runs scripts that invoke pnpm; those invocations need the same config to fully address #7342.
### Fix Focus Areas
- Dockerfile[121-127]
- Dockerfile[154-161]
- Dockerfile[174-191]
### Suggested change
In the Dockerfile `build` stage, add `.npmrc` to the files copied into the image (e.g., alongside `pnpm-workspace.yaml` and `package.json`) before any `RUN ...install...` steps that execute pnpm. This ensures `package-import-method=hardlink` applies consistently to all pnpm invocations during the Docker build.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #7342. pnpm's default
package-import-method=autoends up usingcopyfile+copy_file_range, which fails on ZFS withEAGAIN: resource temporarily unavailable(upstream pnpm/pnpm#7024).docker compose buildtherefore aborts insideRUN pnpm installon any host with a ZFS root. Forcepackage-import-method=hardlinkin the project-level.npmrcso every pnpm invocation — Dockerfile,bin/installDeps.sh,bin/installLocalPlugins.sh,bin/updatePlugins.sh— picks it up automatically instead of requiring per-command flags. Hardlinks are fast, save disk, and work on every filesystem Etherpad supports.