pnpm ERR_PNPM_LOCKFILE_CONFIG_MISMATCH: Fix Catalogs in Docker

Confirm that the Docker context lost the workspace file#

Catalogs are defined in pnpm-workspace.yaml and referenced from package manifests with the catalog: protocol. Check the files that actually reach the failing layer:

1
pnpm --version
2
test -f pnpm-workspace.yaml && echo 'workspace config present' || echo 'workspace config missing'
3
rg -n '^(catalog|catalogs):' pnpm-workspace.yaml pnpm-lock.yaml
4
pnpm install --frozen-lockfile

The error is especially easy to reproduce when a pruning step copies only the root manifest and lockfile into a new directory. The official pnpm issue #10551 records this exact production-build shape for pnpm 10.24.0 and later. The version matters when comparing logs, but the underlying check is the same: a lockfile containing catalog information is being installed without the workspace configuration that defined it.

Do not hand-edit pnpm-lock.yaml to remove catalogs:. The lockfile is a generated record, and deleting part of it can leave the resolved importers inconsistent with the manifests that use catalog:.

Keep the workspace intact during the install stage#

If the image is built from the monorepo, let the install stage see the workspace file and the package manifests described by it:

1
FROM node:22-slim AS build
2

3
WORKDIR /app
4
RUN corepack enable
5

6
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
7
COPY packages ./packages
8

9
RUN pnpm install --frozen-lockfile
10
RUN pnpm run -r build

The important part is not the exact base image. It is that pnpm-workspace.yaml, every workspace manifest needed by the lockfile, and the same pnpm major version are present before the frozen install. If your workspace uses a different package glob, copy that directory structure rather than copying only one application package.

The pnpm Docker guide shows the same boundary in its monorepo recipe: the build context contains both pnpm-lock.yaml and pnpm-workspace.yaml before pnpm install --frozen-lockfile runs. Keep the cache optimization after the file set is correct; a fast failure is still a failure.

Use pnpm deploy for a portable production stage#

When the final image should contain one workspace package and only its production dependencies, build and deploy from the intact workspace first:

1
FROM node:22-slim AS build
2

3
WORKDIR /app
4
RUN corepack enable
5
COPY . .
6

7
RUN pnpm install --frozen-lockfile
8
RUN pnpm run -r build
9
RUN pnpm --filter=web --prod deploy /prod/web
10

11
FROM node:22-slim AS runtime
12
WORKDIR /app
13
ENV NODE_ENV=production
14
COPY --from=build /prod/web ./
15
CMD ["pnpm", "start"]

pnpm deploy creates an isolated node_modules directory and a portable target directory from a workspace package. Current pnpm versions expect the injectWorkspacePackages: true setting for the default deploy implementation; use the documented --legacy path only when that is an intentional compatibility choice. The final stage should copy the generated deploy directory, not reconstruct a partial workspace by guessing which lockfile fields are safe to drop.

This pattern also separates the two jobs in a multi-stage image: the build stage needs the complete workspace, while the runtime stage receives the already-pruned package. It avoids asking a standalone production directory to interpret catalog definitions that no longer exist there.

Avoid the tempting unfrozen-install workaround#

pnpm install --no-frozen-lockfile may regenerate state in a disposable directory, but it changes the guarantee that the committed lockfile is the install input. Do not use it as the normal production fix just because the Docker layer is missing pnpm-workspace.yaml.

If the target really is a standalone project, make that conversion explicit: replace catalog references with concrete dependency ranges in the generated manifest, create a lockfile for that standalone context, and review the result. If the target is still a workspace package, preserve the workspace or use pnpm deploy; do not silently resolve a different dependency graph during the image build.

The diagnostic rule is: a catalog-aware lockfile must be paired with the workspace configuration that defines the catalogs. In Docker, keep that pair together until pnpm has finished resolving dependencies, then copy a self-contained deployment artifact into the final image.

FAQ#