Researched guidance: How can a Pages build diagnose a missing package-manager executable?

Summary

Diagnose a missing package-manager executable by identifying the Pages build-image generation and literal error first. Current v3 documents npm 10.9.2, pnpm 10.11.1, and Yarn 4.9.1 as preinstalled; automatic dependency installation is enabled unless SKIP_DEPENDENCY_INSTALL=1 or true. v3 does not infer Node/package-manager versions from package.json engines or Yarn/pnpm versions from lockfile versions, so pin versions explicitly. A July 2022 Cloudflare build-image discussion reports historical `yarn: command not found` when yarn.lock was absent; do not generalize that v1-era observation to current v3.

Candidate action

Inspect the build log, exact error, image generation, lockfiles, build command, and version overrides. On v3, pin Node with NODE_VERSION or .nvmrc/.node-version and pnpm/Yarn with PNPM_VERSION/YARN_VERSION. If automatic installation is intentionally bypassed, set SKIP_DEPENDENCY_INSTALL=1 (or true) and provide the complete install/build command. Keep historical missing-yarn-lockfile behavior separate from current v3 guidance.

Applicability

• Cloudflare Pages builds using the current v3 build system and documented preinstalled tools.
• Older v1/v2 behavior where the July 2022 discussion may explain a missing Yarn executable.
• Projects that intentionally bypass automatic dependency installation with SKIP_DEPENDENCY_INSTALL.

Procedure

• Capture the exact missing-executable text and first failing command from the Pages deployment build log, plus the build-image generation if shown.
• Inventory committed lockfiles and configured build command; record NODE_VERSION, PNPM_VERSION, YARN_VERSION, and .nvmrc/.node-version without secrets.
• For v3, compare the requested manager with the documented preinstalled tools and explicitly pin required versions; do not rely on package.json `engines` or lockfile-version inference.
• If automatic install is the conflict, set SKIP_DEPENDENCY_INSTALL to `1` or `true` and make the build command perform the intended install/build. This is only a proposed configuration path until rerun.
• For an older image, treat the July 2022 discussion’s `yarn: command not found` without yarn.lock as historical evidence only; it is not current-v3 proof.
• Rerun after a change and record that result separately as execution evidence; this research does not establish PASS, FAIL, or independent reproduction.

Key findings

• Current v3 lists npm 10.9.2, pnpm 10.11.1, and Yarn 4.9.1; PNPM_VERSION/YARN_VERSION override versions and SKIP_DEPENDENCY_INSTALL=1 or true disables automatic dependency installation. (S1)
• v3 does not support detecting Yarn/pnpm versions from lockfile versions or Node/package managers from package.json engines. (S1)
• The 2023 build-system announcement says its then-new system ran npm ci and yarn --pure-lockfile before the build command and added pnpm/Yarn support, with rollout qualifiers. (S3)
• The July 2022 official-repository discussion reports Yarn availability conditioned on yarn.lock and the resulting `yarn: command not found`; this is historical, not v3 confirmation. (S4)
• The official changelog records pnpm 10 support on 2025-02-26 and advises retrying builds that failed due to the unsupported version. (S2)

Known limitations

• Current docs list tools and unsupported version-detection mechanisms but do not specify the complete lockfile-to-package-manager selection algorithm or every repository-layout behavior.
• The missing-Yarn-lockfile observation is historical, dated July 2022, and should not be generalized to v3.
• No live Pages build, private repository, deployment, or account was accessed; no execution outcome is claimed.
• Preinstalled defaults can change; pin critical versions.

Obsolete approaches

• Do not assume package.json `engines` selects Node.js or package-manager versions on v3.
• Do not use the historical missing-yarn-lockfile explanation as a definitive current-v3 diagnosis.
• Do not treat web documentation as executed evidence.

Negative results

• Current official docs provide no literal current missing-package-manager error and no complete lockfile selection algorithm.
• The changelog confirms pnpm 10 support but does not itself give a missing-executable diagnosis.

Evidence boundary

• Public-source research only; no secrets, private sources, account data, or deployment access.
• Proposed guidance only; not an executed PASS, FAIL, or independent reproduction.
• Historical GitHub discussion evidence is explicitly separated from current v3 documentation.
• Researched proposed guidance; not executed or independently reproduced.

What remains unknown

• The target build’s image generation, exact error text, lockfiles, build command, and version overrides.
• Whether the target issue is caused by v3 pinning, automatic install, or repository-layout-specific selection.
• Whether any configuration change succeeds; a live rerun is required.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Build image / language support and tools · Cloudflare Pages docs · official_documentation · accessed 2026-09-27
• S2 Changelog · Cloudflare Pages docs · official_documentation · accessed 2026-09-27
• S3 Modernizing the toolbox for Cloudflare Pages builds · Cloudflare Blog · official_documentation · accessed 2026-09-27
• S4 cloudflare/pages-build-image Discussion #1 · official_repository · accessed 2026-09-27