El error unexpected argument '--frozen-lockfile' found sale porque tu npm install -g pnpm ya instala pnpm 12, y se arregla escribiendo --no-frozen-lockfile en lugar de --frozen-lockfile false. pnpm 12 es una reescritura en Rust y su analizador de argumentos no acepta un valor suelto detrás de una bandera booleana: lee false como el nombre de un paquete. Esta guía reproduce el fallo dentro de un docker build, lo corrige y repasa los otros dos errores que vas a encontrar en la misma actualización. Lo probé el 27 de octubre de 2026 en Linux arm64 con Docker 29.5.2, node:24-slim (Node 24.22.1) y pnpm 12.15.0. Tienes la versión en inglés de esta guía.

Puntos clave

  • El 27 de octubre de 2026 la etiqueta latest de pnpm en npm apunta a 12.15.0, así que un npm install -g pnpm sin versión instala pnpm 12.
  • --frozen-lockfile false falla con código de salida 2; --no-frozen-lockfile y --frozen-lockfile=false (con signo igual) funcionan.
  • Una clave desconocida en pnpm-workspace.yaml pasa de aviso a error ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS cuando el proyecto fija la versión de pnpm en packageManager.
  • Volver a pnpm 11 desde un pnpm 12 global descarga un ejecutable de 150,7 MB que necesita libatomic.so.1, y node:24-slim no la trae.
  • La corrección duradera es fijar la versión exacta: npm install -g pnpm@12.15.0 en el Dockerfile y "packageManager": "pnpm@12.15.0" en package.json.

¿Qué significa unexpected argument ‘–frozen-lockfile’ found?

Significa que pnpm 12 no reconoce false como valor de --frozen-lockfile y lo trata como un argumento posicional. En pnpm 11 y anteriores, pnpm install --frozen-lockfile false desactivaba el modo de lockfile congelado. En pnpm 12, install con un argumento suelto se convierte en pnpm add, y el analizador se queja de la bandera. Esta es la salida exacta de un docker build con un Dockerfile que instala pnpm sin fijar versión:

$ pnpm install --frozen-lockfile false
error: unexpected argument '--frozen-lockfile' found

  tip: to pass '--frozen-lockfile' as a value, use '-- --frozen-lockfile'

Usage: pnpm add [OPTIONS] <PACKAGE_NAMES>...

For more information, try '--help'.

El proceso sale con código 2 y docker build se detiene con did not complete successfully: exit code: 2. El consejo del propio mensaje (-- --frozen-lockfile) no sirve para este caso, porque pasaría la bandera como nombre de paquete. pnpm install --frozen-lockfile true falla igual: el problema es el valor separado por un espacio, no el false.

¿Por qué te ha llegado pnpm 12 sin pedirlo?

Porque npm install -g pnpm instala lo que marque la etiqueta latest, y esa etiqueta ya es pnpm 12. Cuando pnpm publicó la versión 12.0.0, el 26 de agosto de 2026, el anuncio decía que latest seguía en la rama 11. Hoy el registro de npm devuelve latest: 12.15.0, latest-11: 11.28.8 y latest-10: 10.34.9. Cualquier Dockerfile o paso de integración continua (CI) que instale pnpm sin versión ha saltado de mayor sin que nadie toque el repositorio.

El salto es grande. La entrada de la versión 12.0[1] lo resume en dos frases: "pnpm 12 is stable. It is a rewrite of pnpm in Rust." El paquete pnpm ya no trae JavaScript para ejecutar; descarga un binario nativo por plataforma. En mi contenedor ese binario ELF ocupa 45,3 MB, y el ejecutable autónomo de pnpm 11 (que incluye su propio Node) ocupa 150,7 MB:

Tamaño del ejecutable de pnpm instalado en node:24-slim arm64 MB
pnpm 12.15.0, binario nativo
45,3 MB
pnpm 11.28.9, @pnpm/exe autónomo
150,7 MB
Ver tabla de valores
VersiónMB
pnpm 12.15.0, binario nativo45,3 MB
pnpm 11.28.9, @pnpm/exe autónomo150,7 MB

Medido con ls -l el 27 de octubre de 2026 en Linux arm64; pnpm 12 instalado con npm install -g, pnpm 11 descargado por el cambio de versión de packageManager.

La adopción ya es amplia. La API de descargas por versión de npm cubre la semana anterior al 27 de octubre de 2026. En ella, pnpm 12 sumó el 20,3 % de las descargas del paquete, frente al 35,7 % de pnpm 11 y el 34,1 % de pnpm 10.

Cómo arreglar el error en un Dockerfile

La corrección tiene dos partes: cambiar la bandera y fijar la versión. Este es el Dockerfile que reproduce el fallo, con un proyecto mínimo de dos dependencias y su pnpm-lock.yaml:

FROM node:24-slim
RUN npm install -g pnpm
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile false

Y este es el que construye sin error. Fija pnpm a 12.15.0 y usa la bandera en su forma booleana:

FROM node:24-slim
RUN npm install -g pnpm@12.15.0
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

La construcción termina con Done in … using pnpm v12.15.0. Si lo que quieres es desactivar el modo congelado (por ejemplo, en una rama que regenera el lockfile), escribe --no-frozen-lockfile. Para localizar todas las apariciones en tu repositorio, busca la forma antigua en los ficheros que suelen contenerla:

grep -rnE "frozen-lockfile +(false|true)" \
  .github .gitlab-ci.yml Dockerfile* Makefile scripts 2>/dev/null

El mantenedor principal de pnpm, Zoltan Kochan, respondió así en la incidencia 14741[2], que pedía recuperar la forma antigua: "we can’t really support values with boolean flags. Unless maybe there is an explicit = sign". Lo comprobé: --frozen-lockfile=false funciona en 12.15.0, pero --no-frozen-lockfile es la forma que documenta la guía de migración.

¿Cómo compruebo que el modo congelado sigue protegiendo el build?

Comprueba que --frozen-lockfile rechaza un lockfile desfasado. Añadí una dependencia a package.json sin regenerar pnpm-lock.yaml y ejecuté la instalación con CI=true, como haría un runner:

$ CI=true pnpm install --frozen-lockfile
Error: ERR_PNPM_OUTDATED_LOCKFILE

  × installing dependencies
  ╰─▶ Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up
      to date with package.json.

        Failure reason:
        specifiers in the lockfile don't match specifiers in package.json:
      * in importers["."]:
      * 1 dependency was added: is-even@1.0.0

El código de salida es 1, que es lo que quieres en CI. Sin la bandera y con CI=true, pnpm 12 también congela el lockfile por defecto y muestra el mismo error. El lockfile que genera pnpm 12 sigue en lockfileVersion: '9.0', el mismo formato que pnpm 10 y 11, así que no hace falta regenerarlo para el cambio de versión.

Error ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS

Este segundo error aparece cuando pnpm-workspace.yaml contiene una clave que pnpm 12 no conoce y el proyecto fija la versión de pnpm. Sin fijar versión, la misma clave produce solo un aviso y la instalación sigue. Lo reproduje con una errata deliberada, onlyBuiltDependenciez:

$ pnpm install
Error: ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS

  × The following settings in pnpm-workspace.yaml are not recognized by this
  │ version of pnpm: "onlyBuiltDependenciez" (did you mean
  │ "onlyBuiltDependencies"?).
  help: The project pins pnpm to a version the running pnpm satisfies, so
        these settings cannot be meant for a different pnpm version. Remove
        them from pnpm-workspace.yaml or fix their spelling.

La corrección es borrar la clave o escribirla bien. Además de las erratas, revisa las claves que pnpm ya no lee. En mi prueba, pnpm 12.15.0 ignora useNodeVersion (sugiere nodeVersion), managePackageManagerVersions y packageManagerStrict, y descarta cualquier clave en kebab-case como node-linker con el aviso use "nodeLinker". pnpm 11.28.8 ya daba esos mismos avisos, de modo que si vienes de pnpm 10 el salto es doble.

Los subcomandos pnpm config no fallan por este motivo, así que puedes usarlos para editar el fichero.

Error libatomic.so.1 al volver a pnpm 11 desde pnpm 12

Fijar "packageManager": "pnpm@11.28.9" parece la salida rápida, pero en node:24-slim falla de otra forma. El pnpm 12 global intenta cambiar a la versión fijada, descarga el ejecutable autónomo @pnpm/exe de pnpm 11 y este no arranca:

$ pnpm -v
.../@pnpm/exe/pnpm: error while loading shared libraries:
libatomic.so.1: cannot open shared object file: No such file or directory

En tu terminal es una sola línea; aquí la he partido para que quepa. La causa es que node:24-slim se basa en Debian 12.15 y no incluye libatomic1, mientras que node:26-slim (Debian 13.7) sí la trae. La incidencia 11531 de pnpm[3] documenta el mismo mensaje con el instalador de pnpm 11 en imágenes mínimas. Tienes dos arreglos que comprobé:

  • Instalar la biblioteca: apt-get install -y libatomic1 en la imagen; después pnpm -v devuelve 11.28.9 y la instalación termina
  • Instalar pnpm 11 con npm: npm install -g pnpm@11 usa el paquete JavaScript y no el ejecutable autónomo; el build terminó con using pnpm v11.28.9 y el comando antiguo sin cambios

Volver a pnpm 11 compra tiempo, pero deja pendiente un salto de versión mayor. Si eliges este camino, apúntalo como deuda en tu gestor de dependencias; la comparativa entre Dependabot y Renovate explica cómo agrupar ese tipo de actualizaciones.

¿Qué pasa con Corepack y con un pnpm global antiguo?

Ninguno de los dos me dio problemas en Linux. En node:24-slim, Corepack 0.36.0 descargó el binario de pnpm 12.15.0 para linux-arm64 desde packageManager e instaló el proyecto sin errores. Un pnpm 10.34.9 global y otro 10.6.2 cambiaron a la versión fijada 12.15.0 y terminaron con Done in … using pnpm v12.15.0.

Ten en cuenta dos excepciones. node:26-slim no incluye Corepack (corepack: not found), así que en esa imagen instala pnpm con npm install -g pnpm@12.15.0. Y la incidencia 16675[4] documenta un fallo distinto: un pnpm 12 global anterior a la versión fijada lee pnpm-workspace.yaml antes de cambiar de versión y se para si encuentra un ajuste que todavía no conoce. Si te pasa, actualiza el pnpm global a la versión que fija el proyecto.

En Alpine, node:22-alpine instaló y ejecutó pnpm 12.15.0 sin bibliotecas extra. Si estás eligiendo imagen base, la comparativa de Wolfi, Alpine y distroless mide qué trae cada una.

Preguntas frecuentes

¿Es lo mismo –frozen-lockfile=false que –no-frozen-lockfile en pnpm 12?

En mi prueba con 12.15.0 los dos desactivan el modo congelado y regeneran el lockfile. La forma documentada es --no-frozen-lockfile, y el mantenedor de pnpm solo dejó abierta la posibilidad del signo igual. Usa --no-frozen-lockfile en scripts nuevos.

¿Tengo que regenerar pnpm-lock.yaml al pasar a pnpm 12?

No por el formato: pnpm 12 escribe lockfileVersion: '9.0', igual que pnpm 10 y 11. Según la entrada de la versión 12.0, la primera instalación puede reescribir las variantes de paquetes con dependencias cíclicas. Espera un cambio único en el lockfile y súbelo en un commit aparte.

¿Cómo evito que la próxima versión mayor me rompa el build otra vez?

Fija la versión exacta en dos sitios: en el Dockerfile o paso de CI (npm install -g pnpm@12.15.0) y en package.json ("packageManager": "pnpm@12.15.0"). Si además quieres retrasar las versiones recién publicadas, la guía para blindar npm con allowScripts y min-release-age cubre esa parte.

Conclusión

unexpected argument '--frozen-lockfile' found no es un fallo de tu proyecto: es pnpm 12 entrando por un npm install -g pnpm sin versión. Cambia --frozen-lockfile false por --no-frozen-lockfile, revisa las claves de pnpm-workspace.yaml antes de fijar la versión y, si decides volver a pnpm 11 en node:24-slim, añade libatomic1 o instálalo con npm. Después fija la versión en el Dockerfile y en packageManager para que el siguiente salto sea una decisión tuya.

Fuentes: [1] pnpm, notas de la versión 12.0[1], [2] pnpm, incidencia 14741 sobre –frozen-lockfile false[2], [3] pnpm, incidencia 16675 sobre el cambio de versión[4], [4] pnpm, incidencia 11531 sobre libatomic.so.1[3], [5] npm, paquete pnpm y sus etiquetas[5], [6] Docker Hub, imagen oficial de Node.js[6].

Fuentes

  1. entrada de la versión 12.0
  2. incidencia 14741
  3. incidencia 11531 de pnpm
  4. incidencia 16675
  5. npm, paquete pnpm y sus etiquetas
  6. Docker Hub, imagen oficial de Node.js