Solución de problemas del registro

401 Unauthorized — aunque tengo la sesión iniciada

Tres causas comunes:

1. Falta always-auth=true en .npmrc — yarn 1 se niega a enviar el bearer en las peticiones GET sin él. npm/pnpm/bun ignoran el flag de forma inofensiva, así que simplemente añádelo siempre.
2. Token revocado — comprueba Packages → Manage tokens en el panel. Si la fila ha desaparecido, genera uno nuevo.
3. Host incorrecto en la línea de autenticación — la línea debe usar el host exacto que sirve el registro, p. ej. //pier.example.com/registry/npm/:_authToken=…. Una barra final sobrante o ausente que no coincida provoca un 401 silencioso.

401 específicamente en yarn 4

Yarn berry necesita npmAlwaysAuth: true en .yarnrc.yml (no en .npmrc):

npmRegistryServer: "https://YOUR-PIER-HOST/registry/npm/"
npmAuthToken: "pier_npm_…"
npmAlwaysAuth: true
nodeLinker: node-modules

Sin él, yarn 4 solo envía el bearer en npm publish, no en npm install.

409 Conflict al publicar

Estás volviendo a publicar una versión que ya existe. Incrementa la versión en package.json (npm version patch / minor / major). Pier rechaza las republicaciones por diseño — coincide con la semántica de npm.

Si quieres reemplazar de verdad una versión publicada, ejecuta primero npm unpublish @your-org/[email protected] y luego npm publish con los nuevos bytes. Cuidado: los consumidores externos que fijaron X.Y.Z y lo tienen en su lockfile obtendrán discrepancias de integridad.

El ETag no hace cortocircuito (sin 304)

La respuesta del packument lleva un ETag. Si tu cliente envía If-None-Match con ese mismo valor, Pier devuelve 304. Si ves respuestas 200 completas cada vez, comprueba:

• El encabezado de autenticación es el mismo que antes. Algunas bibliotecas HTTP omiten If-None-Match cuando la petición cambia (distinto Accept, etc.) — asegúrate de que tu encabezado Accept sea estable.
• Compresión — si la respuesta se comprimió con gzip y el cliente la solicita sin comprimir (o viceversa), el ETag no cambia, pero algunos intermediarios eliminan el If-None-Match. Usa curl con -H "Accept-Encoding: gzip" para reproducirlo de forma fiable.

Confusión con el packument abreviado

Bun (y npm reciente) envía Accept: application/vnd.npm.install-v1+json — Pier devuelve un JSON más ligero (sin README, sin marcas de tiempo históricas). Si tu herramienta espera el packument completo, quita el Accept abreviado.

502 Bad Gateway

Traefik está activo pero Pier no es accesible en su puerto de loopback. Comprueba systemctl status pier en el host. Si pier está activo, verifica que proxy.platform_domain coincida con el host al que estás accediendo.

ENOENT / 404 en un paquete público que acabo de instalar

Puede que el proxy upstream no esté habilitado. Comprueba Packages → Upstream proxy → Enable upstream proxy — cuando está desactivado, solo se sirven los paquetes publicados de forma privada.

Si el proxy está activado y aun así obtienes un 404, puede que el upstream realmente haya devuelto 404. Pier lo deja pasar (un paquete que genuinamente no existe en npmjs.org debería ser un 404).

”Tarballs on disk” muestra 0 pero acabo de instalar

Puede que el GC con LRU los haya expulsado. El límite de la caché está en Packages → Upstream proxy → Max cache size (MiB) — si está establecido en un valor pequeño (p. ej. 50) e instalaste algo grande como Next.js, los tarballs más antiguos se recuperan.

Establece Max cache size en 0 (ilimitado) si tienes abundante disco.

También puedes volver a descargar una versión concreta desde la página de detalle del paquete — el botón Download latest (X.Y.Z) descarga un único tarball a través de Pier sin lanzar un npm install.

La página de detalle muestra “0 versions” para un paquete que sé que está en caché

Puede que el blob del packument esté vacío (normalmente justo después de una migración que borró las filas por versión). Pier refresca automáticamente el blob al cargar la página de detalle si está vacío — la primera visita podría ser lenta (~1s) mientras lo descarga del upstream. Las visitas posteriores son instantáneas.

Si se queda en 0 tras una recarga, el upstream es inaccesible o devolvió 404. Comprueba journalctl -u pier | grep proxy.

Advertencia de “always-auth” en npm 11

npm warn Unknown project config "always-auth"

npm 11 deprecó el flag pero aún lo respeta. Puedes ignorar la advertencia. Cuando llegue npm 12 y lo elimine, yarn 1 será un problema aparte (para entonces la mayoría de los equipos ya habrán dejado de usarlo).

Relacionado

• Configuración — empieza aquí si eres nuevo.
• Guías por cliente — el archivo de configuración correcto para cada cliente.
• Proxy upstream — para problemas específicos de la caché.