Saltar al contenido

Caché no encontrada para las claves de entrada: causas

Última actualización

Cache not found for input keys es un fallo de caché de actions/cache: ninguna caché guardada coincidió con su key ni con sus restore-keys, así que el paso continúa sin restaurar nada. En la mayoría de los flujos de trabajo es una advertencia y el job sigue, pero si el siguiente paso necesita la caché, puede parecer un fallo. Esta página explica por qué no se encontró la caché y cómo conseguir que coincida. Las reglas proceden de la referencia de caché de dependencias de GitHub, revisada en octubre de 2026.

El mensaje exacto

Cache not found for input keys: Linux-npm-3f1c0d9a2b..., Linux-npm-

Con actions/cache/restore y fail-on-cache-miss: true, en cambio, obtendrá un paso fallido. La primera clave de la lista es su key, y las demás son sus restore-keys. Un fallo en la primera ejecución de una clave nueva es normal: el paso posterior guarda la caché y las ejecuciones siguientes la encuentran.

Cómo funciona la búsqueda

  1. La acción busca una coincidencia exacta de key en la rama actual.
  2. Si no la encuentra, busca coincidencias por prefijo de key y, después, de cada entrada de restore-keys, en orden. Si hay varias coincidencias parciales, devuelve la caché creada más recientemente.
  3. Si tampoco, repite la búsqueda en la rama predeterminada.

Reglas de ámbito: una ejecución puede restaurar cachés de la rama actual o de la rama predeterminada, y las pull requests también pueden restaurar desde la rama base. No pueden restaurar cachés de ramas hermanas o descendientes. Las cachés de etiquetas están aisladas por etiqueta. Las entradas sin acceso durante 7 días se eliminan, y el límite predeterminado es de 10 GB por repositorio.

Causas, de la más probable a la menos probable

1. Es la primera ejecución para esta clave

Cualquier clave nueva falla una vez. Si su clave incluye hashFiles('**/package-lock.json'), cada cambio en el lockfile fallará una vez. No hay nada que corregir. Añada restore-keys para que una coincidencia aproximada restaure algo:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

2. La clave cambia en cada ejecución

Claves como ${{ github.sha }}, ${{ github.run_id }} o una marca de tiempo nunca coinciden con una ejecución anterior. Base la clave en el archivo que determina el contenido (el lockfile), no en el commit. El generador de claves de caché crea claves válidas.

3. La caché está en una rama que no puede leer

Una rama de funcionalidad guarda su caché bajo esa rama, y otra rama de funcionalidad no puede verla. Las ejecuciones de pull requests guardan cachés para la referencia de fusión, así que una PR no calienta la caché de otra. Solución: asegúrese de que la rama predeterminada guarde la caché, por ejemplo con un flujo de trabajo en push a main o una ejecución programada, para que cualquier rama pueda recurrir a ella.

on:
  push:
    branches: [main]
  schedule:
    - cron: "0 3 * * *"

4. La caché fue eliminada

Tras 7 días sin acceso, o cuando el repositorio supera los 10 GB, las entradas se eliminan, primero las menos usadas recientemente. Revise Actions y después Caches en el repositorio, o ejecute gh cache list. Detalles y soluciones en límites de caché de GitHub Actions.

5. El path o el runner.os son distintos

La caché está ligada a su clave y también a su versión, derivada de las rutas y del método de compresión. Cambiar path, o restaurar en un sistema operativo distinto al de guardado, produce un fallo. Incluya runner.os en la clave y mantenga la misma ruta al guardar y al restaurar.

6. El guardado nunca se produjo

El paso posterior solo guarda si el job terminó correctamente y la clave no tuvo una coincidencia exacta. Si el job falló antes del final, no se guardó nada. Use actions/cache/save con if: always() cuando quiera guardar tras un fallo:

- uses: actions/cache/restore@v4
  id: cache
  with: { path: ~/.cache/pip, key: pip-${{ hashFiles('requirements.txt') }} }
- run: pip install -r requirements.txt
- uses: actions/cache/save@v4
  if: always() && steps.cache.outputs.cache-hit != 'true'
  with: { path: ~/.cache/pip, key: pip-${{ hashFiles('requirements.txt') }} }

7. Dos jobs compiten por guardar la misma clave

Las entradas de caché son inmutables. Si dos celdas de una matriz guardan la misma clave, gana una y la otra registra un error de reserva. Dé a cada celda su propia clave o guarde desde un solo job.

Use la salida cache-hit

cache-hit es true solo con una coincidencia exacta de clave, no con una coincidencia de restore-key. Úsela para omitir trabajo:

- uses: actions/cache@v4
  id: cache
  with:
    path: node_modules
    key: nm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
- if: steps.cache.outputs.cache-hit != 'true'
  run: npm ci

Recuerde que una coincidencia de restore-key deja cache-hit en false aunque sí restaure archivos.

Cuándo la caché no ayuda

Si las cachés fallan constantemente, son muy grandes o restaurarlas es más lento que la instalación que reemplazan, un runner con cachés locales ya calientes puede ser mejor opción. Las máquinas de compiler.dev mantienen listas las cachés de dependencias, de git y de capas de Docker, así que no tiene que gestionar claves para ellas; consulte los precios. Otras opciones: caché en GitHub Actions y caché de capas de Docker. Las cachés grandes también provocan No space left on device.

Cómo prevenirlo

  1. Base las claves en lockfiles, añada una alternativa con restore-keys e incluya runner.os.
  2. Guarde las cachés desde la rama predeterminada para que cada PR pueda restaurarlas.
  3. Mantenga el tamaño total de la caché bastante por debajo de 10 GB.
  4. Revise la tasa de aciertos en sus registros cada semana, y use el estimador de ahorro por aciertos de caché para ver lo que cuesta un fallo.

Preguntas frecuentes

¿Es «Cache not found for input keys» un error?

No, es un mensaje informativo sobre un fallo. El job continúa a menos que establezca fail-on-cache-miss: true.

¿Por qué tengo un fallo de caché en cada pull request?

Las cachés de PR están limitadas a la referencia de fusión, y una PR solo puede restaurar desde sí misma, su rama base y la rama predeterminada. Asegúrese de que la rama predeterminada guarde la caché.

¿Cuánto dura una caché de GitHub Actions?

Siete días desde el último acceso, salvo que se elimine antes por superar el límite del repositorio.

¿Por qué mi caché se restaura pero cache-hit es false?

Una coincidencia de restore-key (prefijo) restaura archivos pero no cuenta como acierto exacto, así que cache-hit es false.