Cache not found for input keys: 原因と対処法
最終更新
Cache not found for input keys は actions/cache によるキャッシュミスです。保存済みのキャッシュが key や restore-keys に一致しなかったため、ステップはキャッシュを復元せずに続行します。多くのワークフローでは警告にとどまりジョブは継続しますが、後続のステップがキャッシュを必要とする場合は失敗のように見えることがあります。本ページでは、キャッシュが見つからなかった理由と、ヒットさせる方法を説明します。ルールは GitHub の依存関係キャッシュのリファレンスに基づき、2026 年 10 月時点で確認しています。
表示される正確なメッセージ
Cache not found for input keys: Linux-npm-3f1c0d9a2b..., Linux-npm-
actions/cache/restore で fail-on-cache-miss: true を指定している場合は、代わりにステップが失敗します。最初に列挙されたキーが key、それ以外が restore-keys です。新しいキーの初回実行でミスするのは正常な動作です。post ステップでキャッシュが保存され、以降の実行でヒットするようになります。
検索の仕組み
- アクションはまず、現在のブランチ内で
keyと完全一致するキャッシュを探します。 - 見つからない場合は、
keyと、restore-keysの各エントリを順に前方一致で探します。前方一致が複数ある場合は、最も新しく作成されたキャッシュを返します。 - それでも見つからない場合は、デフォルトブランチで同じ検索を繰り返します。
適用範囲のルール: 実行では現在のブランチまたはデフォルトブランチのキャッシュを復元できます。プルリクエストでは、ベースブランチのキャッシュも復元できます。兄弟ブランチや子ブランチのキャッシュは復元できません。タグのキャッシュはタグごとに分離されます。7 日間アクセスのなかったエントリは削除され、リポジトリごとの既定の上限は 10 GB です。
考えられる原因(可能性の高い順)
1. このキーで初めての実行である
新しいキーは初回に必ずミスします。キーに hashFiles('**/package-lock.json') を含めている場合は、ロックファイルが変更されるたびに一度ミスします。これは修正の必要がない動作です。近い一致からでも復元できるように restore-keys を追加してください。
- uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
npm-${{ runner.os }}-
2. 実行ごとにキーが変わる
${{ github.sha }}、${{ github.run_id }}、タイムスタンプなどを含むキーは、過去の実行と一致することがありません。コミットではなく、内容を決めるファイル(ロックファイル)をキーにしてください。キャッシュキービルダーを使うと、安全なキーを生成できます。
3. キャッシュが参照できないブランチに保存されている
フィーチャーブランチのキャッシュは、そのブランチ内に保存されます。別のフィーチャーブランチからは参照できません。プルリクエストの実行はマージ参照に対してキャッシュを保存するため、あるPRが別のPRのキャッシュを温めることはありません。対処法: デフォルトブランチでもキャッシュが保存されるようにしてください。たとえば main への push で動くワークフローや定期実行を使うと、すべてのブランチがフォールバックできるようになります。
on:
push:
branches: [main]
schedule:
- cron: "0 3 * * *"
4. キャッシュが削除された
7 日間アクセスがない場合、またはリポジトリが 10 GB を超えた場合、最も長く使われていないエントリから順に削除されます。Actions の Caches を確認するか、gh cache list を実行してください。詳細と対処法は GitHub Actions のキャッシュ上限を参照してください。
5. path または runner.os が異なる
キャッシュはキーに加え、パスと圧縮方式から導出されるバージョンにも紐づきます。path を変更したり、保存時と異なる OS で復元したりすると、ミスになります。キーに runner.os を含め、保存と復元でパスを同一に保ってください。
6. 保存が行われなかった
post ステップは、ジョブが成功し、かつキーが完全一致していなかった場合にのみ保存します。ジョブが途中で失敗した場合は、何も保存されません。失敗後も保存したい場合は、actions/cache/save に if: always() を指定してください。
- 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. 2 つのジョブが同じキーへの保存を競合している
キャッシュエントリは不変です。2 つのマトリクスセルが同じキーで保存しようとすると、一方のみが成功し、もう一方は予約エラーをログに出力します。各セルに個別のキーを割り当てるか、1 つのジョブからのみ保存してください。
cache-hit 出力を使う
cache-hit は、キーが完全一致した場合にのみ true になります。restore-key の一致では true になりません。作業をスキップするために使用できます:
- 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
restore-keys で一致した場合は、ファイルは復元されても cache-hit は false になる点に注意してください。
キャッシュが役に立たない場合
キャッシュが何度もミスする、サイズが大きすぎる、あるいは復元の方が置き換えるインストールより遅い場合は、ローカルキャッシュが温まったランナーを使う方が適している場合があります。compiler.dev のマシンは依存関係、git、Docker レイヤーのキャッシュを事前に用意しているため、そのためのキーを管理する必要はありません。詳細は料金をご覧ください。その他の選択肢として、GitHub Actions のキャッシュや Docker レイヤーキャッシュがあります。また、キャッシュが大きすぎると No space left on device が発生することもあります。
予防方法
- ロックファイルをキーにし、
restore-keysのフォールバックを追加して、runner.osを含めてください。 - デフォルトブランチからキャッシュを保存し、すべての PR が復元できるようにしてください。
- キャッシュの合計サイズは 10 GB を十分下回るように保ってください。
- ログでヒット率を週ごとに確認し、キャッシュヒットによる節約額の見積もりツールでミスの際のコストを把握してください。
よくある質問
「Cache not found for input keys」はエラーですか?
いいえ、ミスを知らせる情報メッセージです。fail-on-cache-miss: true を設定していない限り、ジョブは継続します。
なぜすべてのプルリクエストでキャッシュミスになるのですか?
PR のキャッシュはマージ参照に紐づき、PR は自身、ベースブランチ、デフォルトブランチからのみ復元できます。デフォルトブランチでもキャッシュが保存されるようにしてください。
GitHub Actions のキャッシュはどのくらい保持されますか?
最後のアクセスから 7 日間です。ただし、リポジトリの上限を超えた場合はそれより早く削除されることがあります。
キャッシュは復元されるのに cache-hit が false になるのはなぜですか?
restore-key(前方一致)による一致ではファイルは復元されますが、完全一致としては扱われないため、cache-hit は false になります。
関連記事
- GitHub Actions で Cargo と Rust のビルドをキャッシュするSwatinem/rust-cache または actions/cache を使用して、GitHub Actions で Cargo レジストリ、git 依存関係、target ディレクトリをキャッシュします。キャッシュが肥大化しないように注意します。
- GitHub Actions で Go モジュールとビルドキャッシュをキャッシュするsetup-go または actions/cache を使用して、GitHub Actions で Go モジュール(GOMODCACHE)とビルドキャッシュ(GOCACHE)をキャッシュします。キー、go.sum、キャッシュヒットの確認方法を解説します。
- GitHub Actions で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。