Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 1: Docker & Node.js Fatal Errors6 min readVerified

Fixing ERR_PNPM_OUTDATED_LOCKFILE Cannot Install with frozen-lockfile in Docker

Solve ERR_PNPM_OUTDATED_LOCKFILE during Docker builds and CI pipelines without disabling --frozen-lockfile. Pin pnpm versions via Corepack, sync workspace overrides, and configure BuildKit caches.

TL;DR — Immediate Production Fix

The error ERR_PNPM_OUTDATED_LOCKFILE: Cannot install with "frozen-lockfile" occurs during docker build when the pnpm version inside your Docker image (e.g., pnpm v9.x fetched via npm i -g pnpm) uses a different lockfile resolution algorithm than the pnpm version on your local machine (e.g., pnpm v8.x or v10.x), or when a monorepo child package.json was copied without copying pnpm-workspace.yaml and .npmrc first. Fix it permanently without losing deterministic builds by pinning packageManager in package.json and running corepack enable && corepack prepare inside your Dockerfile.

Verified Root Causes in Production Environments

  • Unpinned Global pnpm Install in Dockerfile: Running RUN npm install -g pnpm inside a Dockerfile always pulls the latest major release from the npm registry, causing lockfile v6.0 / v9.0 schema mismatches against your committed pnpm-lock.yaml.
  • Missing .npmrc or pnpm-workspace.yaml Before pnpm install: If your local setup uses shamefully-hoist=true or auto-install-peers=true in .npmrc, omitting COPY .npmrc ./ before RUN pnpm install --frozen-lockfile changes peer dependency resolution.
  • Monorepo Partial package.json Copy: Copying only the root package.json into a Turborepo or pnpm workspace image without the workspace package.json files invalidates the lockfile importers map.

1. Why Running pnpm install Locally Says 'Up to Date' While Docker Fails

One of the most frustrating aspects of ERR_PNPM_OUTDATED_LOCKFILE is that running pnpm install on your macOS or Windows workstation outputs Already up to date, yet building the exact same Git commit inside a Linux Docker container fails immediately on RUN pnpm install --frozen-lockfile.

This discrepancy happens because pnpm's lockfile checksum validation hashes not only the dependencies and version specifiers in package.json, but also active pnpm settings (such as auto-install-peers, strict-peer-dependencies, and patchedDependencies) plus the major/minor lockfile format version of the pnpm binary itself. When a Dockerfile runs npm i -g pnpm, it pulls the newest upstream release rather than the version that generated pnpm-lock.yaml.

When deploying containerized Node.js and Next.js applications on automated CI/CD runners or PaaS builders such as Coolify and Vexlo Cloud, deterministic dependency installation is enforced via the --frozen-lockfile flag. If the pnpm version inside the container image differs even by a minor lockfile schema revision (for example, pnpm v8.15.0 locally versus pnpm v9.12.0 pulled by npm install -g pnpm in Alpine Linux), pnpm recalculates peer dependency graphs and halts the build immediately. By delegating binary management to Node's built-in Corepack utility, every Docker build layer resolves the exact cryptographic hash declared in your package.json packageManager field.

Additionally, always inspect your .dockerignore file to ensure you are not accidentally excluding .npmrc or workspace patch directories while still copying package.json. If your project uses private GitHub Packages or custom registry scopes, pass your authentication token via Docker BuildKit secret mounts (--mount=type=secret,id=npmrc,target=/root/.npmrc) rather than baking credentials into environment variables.

verify-pnpm-mismatch.sh
bash
# 1. Check your local pnpm version and lockfile version header
pnpm --version
head -n 5 pnpm-lock.yaml
# Example output:
# lockfileVersion: '9.0'

# 2. Pin the exact local pnpm version into package.json for Corepack
pnpm pkg set packageManager="pnpm@$(pnpm --version)"

# 3. Regenerate only the lockfile metadata without mutating node_modules
pnpm install --lockfile-only --no-frozen-lockfile

2. Production Multi-Stage Dockerfile With Corepack & BuildKit Cache

Never resolve ERR_PNPM_OUTDATED_LOCKFILE by passing --no-frozen-lockfile in production CI/CD builds; doing so allows silent sub-dependency upgrades that break production containers. Instead, use Node.js's built-in Corepack manager to read the exact packageManager field from your package.json.

Furthermore, use pnpm fetch combined with Docker BuildKit cache mounts (--mount=type=cache,id=pnpm,target=/pnpm/store). pnpm fetch downloads packages into the virtual store using only pnpm-lock.yaml and .npmrc, keeping your Docker layer cache valid even when you edit scripts in package.json.

Dockerfile.pnpm-corepack
dockerfile
# syntax=docker/dockerfile:1.7
FROM node:20-alpine AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
# Enable Corepack so Docker uses the exact pnpm version in package.json
RUN corepack enable
WORKDIR /app

FROM base AS deps
# Copy lockfile AND configuration files that affect peer resolution
COPY package.json pnpm-lock.yaml .npmrc* pnpm-workspace.yaml* ./

# Pre-fetch packages into BuildKit cache using lockfile only
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm fetch --frozen-lockfile

# Install offline from virtual store
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm install --frozen-lockfile --offline

FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm run build

3. Fixing Turborepo & Monorepo Workspace Importer Errors

In a pnpm monorepo (where pnpm-workspace.yaml defines packages/* and apps/*), a single root pnpm-lock.yaml stores an importers section listing every workspace package.json. If your Dockerfile only copies the root package.json before running pnpm install --frozen-lockfile, pnpm sees missing workspace manifests and throws ERR_PNPM_OUTDATED_LOCKFILE.

Use turbo prune --scope=<app-name> --docker to generate an isolated json/ folder containing only the package.json manifests required for that microservice, along with a pruned pnpm-lock.yaml.

Dockerfile.monorepo
dockerfile
FROM node:20-alpine AS pruner
RUN corepack enable
WORKDIR /app
COPY . .
# Generate pruned lockfile and workspace package.json tree for 'web'
RUN pnpm dlx turbo@^2 prune --scope=web --docker

FROM node:20-alpine AS installer
RUN corepack enable
WORKDIR /app
COPY --from=pruner /app/out/json/ .
COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
RUN pnpm install --frozen-lockfile

Pre-Deployment Verification Checklist

  • Verify package.json contains a pinned "packageManager": "[email protected]" field.
  • Replace RUN npm i -g pnpm in your Dockerfile with RUN corepack enable.
  • Ensure .npmrc and patches/ directories (if used) are copied into the Docker build stage BEFORE running pnpm install --frozen-lockfile.
  • In monorepos, use turbo prune --docker or copy all workspace package.json files prior to installation.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Should I use --no-frozen-lockfile in my Dockerfile to bypass ERR_PNPM_OUTDATED_LOCKFILE?

No. Using --no-frozen-lockfile in Docker or CI pipelines disables lockfile integrity checks and lets pnpm resolve newer transitive dependencies during deployment, which can introduce breaking changes in production. Fix the underlying pnpm version mismatch with Corepack instead.

Why does ERR_PNPM_OUTDATED_LOCKFILE happen when I use overrides or patchedDependencies?

If package.json contains pnpm.overrides or pnpm.patchedDependencies, the referenced patch files (e.g., patches/*.patch) must be copied into the Docker build context before running pnpm install --frozen-lockfile.

How do I update an outdated pnpm-lock.yaml in CI without reinstalling everything locally?

Run pnpm install --lockfile-only --no-frozen-lockfile in your local repository root and commit the updated pnpm-lock.yaml file.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →