Description

When a project specifies "packageManager": "pnpm@..." in package.json, Railpack correctly uses Corepack during the build phase. However, the pnpm binary is missing in the runtime container, causing the start command pnpm run start to fail.

Error:

Starting Container
/bin/bash: line 1: pnpm: command not found

Build log (succeeds):

↳ Detected Node
↳ Using pnpm package manager
↳ Found workspace with 3 packages
↳ Installing pnpm@11.1.2 with Corepack

Steps:
▸ install
  $ npm i -g corepack@latest && corepack enable && corepack prepare --activate
  $ pnpm install --frozen-lockfile --prefer-offline

Deploy:
  $ pnpm run start

Root Cause

Corepack was removed from Node.js starting with v25. (See Node.js docs, nodejs/node#50963)

Railpack handles this correctly during the build phase (in InstallNodeDeps, node.go:262-276) by running:

npm i -g corepack@latest && corepack enable && corepack prepare --activate

This installs the corepack binary and creates a pnpm symlink inside the Node.js installation's bin/ directory, and caches the pnpm distribution at /opt/corepack (COREPACK_HOME).

However, at runtime:

1. The runtime container uses a fresh mise-managed Node.js layer (from miseStep.GetLayer()). The Corepack binary and pnpm shim were build-time modifications to the Node installation and are not carried over.
2. /opt/corepack (COREPACK_HOME) is correctly included in the runtime via buildIncludeDirs (node.go:112-114), but without the corepack binary and pnpm shim it's unusable.
3. node.corepack = true is set in the mise config (node.go:347-349), but since Corepack isn't bundled with Node 25+ and isn't separately installed in the runtime, corepack enable fails silently.

Result: Build works, but runtime fails with pnpm: command not found.

Impact

• All pnpm + Corepack projects using Node.js 25+ are affected
• Build succeeds but container crashes immediately at startup
• Downgrading to Node.js 22 is a workaround (confirmed by affected users)

Proposed Fix

The Corepack binary and pnpm shims need to be available in the runtime. Since /opt/corepack is already included, we can place them there.

Changes needed in core/providers/node/node.go

1. InstallNodeDeps() — After the Corepack setup, copy the binary and shims to /opt/corepack/bin/:

// After: npm i -g corepack@latest && corepack enable && corepack prepare --activate
plan.NewExecShellCommand(
    "mkdir -p /opt/corepack/bin && " +
    "cp -L $(which corepack) /opt/corepack/bin/corepack && " +
    "ln -sf corepack /opt/corepack/bin/pnpm && " +
    "ln -sf corepack /opt/corepack/bin/pnpx",
),

2. Plan() — Add /opt/corepack/bin to runtime PATH and ensure COREPACK_HOME is set:

if p.usesCorepack() {
    ctx.Deploy.Paths = append(ctx.Deploy.Paths, "/opt/corepack/bin")
    ctx.Deploy.Variables["COREPACK_HOME"] = COREPACK_HOME
}

How it works

At runtime, pnpm run start will:

1. Execute the corepack binary (invoked as pnpm)
2. Corepack reads package.json → sees "packageManager": "pnpm@11.1.2"
3. Corepack loads the cached pnpm from COREPACK_HOME=/opt/corepack
4. Executes pnpm run start

No network access needed, zero startup latency.

Related

• Railpack missing corepack update command to handle Node package manager updates #201 — Corepack version resolution issue (related Corepack handling)
• feat: support pnpm installed via corepack #368 (draft PR) — Potentially overlapping fix "feat: support pnpm installed via corepack"
• Node.js docs: Corepack no longer distributed with v25+
• Railway Help Station — Same error, workaround was Node 22 downgrade

🤖 This issue was created with AI assistance.