コンテンツへスキップ

Cache Service Responded With 429: 修正方法

最終更新:

Failed to restore: Cache service responded with 429 は、GitHub Actions のキャッシュサービスがレート制限によりリクエストを拒否したことを意味します。HTTP 429 は「リクエストが多すぎます」を表します。多くのジョブがほぼ同時にキャッシュの復元や保存を行った場合、たとえば大規模なマトリックスが一斉に開始したときに発生しがちです。これ自体は警告であり、キャッシュのステップは復元または保存の失敗を報告しますが、ジョブは処理を続けるため、実行時間が長くなるだけです。

表示される正確なメッセージ

Warning: Failed to restore: Cache service responded with 429
Warning: Failed to save: Cache service responded with 429

GitHub は利用制限のページで、キャッシュサービスの固定のリクエストレートを公開していません。そのため、下回るべき具体的な数値はありません。実践的な対策は、リクエストの数を減らし、同時に集中しないようにすることです。

修正 1: 最新版の actions/cache を使用する

古いバージョンのキャッシュアクションは、GitHub が廃止したレガシーサービスと通信するため、別の形で失敗します。現在のメジャーバージョンを使用してください。

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

actions/setup-node、setup-python、setup-java に組み込まれたキャッシュにも同じことが当てはまります。それぞれ現在のバージョンを使用してください。

修正 2: 保存は一つのジョブだけが行い、他のジョブは復元のみ行う

30 個のマトリックスジョブがそれぞれ同じキャッシュを保存すると、1 つのキャッシュエントリに対して 30 回の保存リクエストが送られ、そのうち 29 回は無駄になります。すべてのジョブで復元し、保存は 1 つのジョブだけで行ってください。

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

# ... install and test ...

- uses: actions/cache/save@v4
  if: matrix.shard == 1 && steps.cache.outputs.cache-hit != 'true'
  with:
    path: ~/.npm
    key: npm-${{ hashFiles('**/package-lock.json') }}

復元ステップの id: cache により、save の条件で cache-hit の出力を参照できます。

修正 3: 大規模マトリックスの開始を遅らせる

strategy.max-parallel は同時に実行されるマトリックスジョブの数を制限します。これによりキャッシュへのリクエストも分散されます。

strategy:
  max-parallel: 10
  matrix:
    shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

修正 4: キャッシュエントリの数を減らし、サイズを大きくする

1 つのジョブで小さなキャッシュを複数使うと、リクエストも複数になります。同じキーを共有するキャッシュパスはまとめ、ダウンロードが速いものはキャッシュしないようにしてください。詳しくは GitHub Actions のキャッシュ と キャッシュの制限 を参照してください。

修正 5: 再実行する

レート制限は時間が経つと解除されます。一時的な問題であれば、失敗したジョブを再実行してください。毎回発生する場合は、上記の修正を適用してください。

キャッシュが見つからないためにジョブが失敗する場合

復元時に 429 が発生すると、キャッシュミスになります。キャッシュに依存する後続のステップが失敗した場合は、Cache not found for input keys を参照してください。キャッシュミスをビルドの失敗とする場合を除き、fail-on-cache-miss: true は設定しないでください。

予防方法

  1. actions/cache@v4 以降に固定し、Dependabot で更新してください。
  2. 保存は一つのジョブから行い、復元はどこからでも行ってください。
  3. 大規模な分岐には、マトリックスの並列数を制限してください。
  4. 多数の小さなキャッシュより、厳選した少数のキャッシュを優先してください。

よくある質問

429 でワークフローは失敗しますか?

デフォルトでは失敗しません。キャッシュのステップは警告を出力し、ジョブは続行されます。ただし、キャッシュがないため実行時間が大幅に長くなることがあります。

これは GitHub API のレート制限と同じですか?

いいえ。これはキャッシュサービスのものです。REST API の制限については API rate limit exceeded を参照してください。

セルフホストランナーならこの問題を回避できますか?

それだけでは回避できません。セルフホストランナーも同じ GitHub のキャッシュサービスを使用するためです。ランナーのディスク上にローカルキャッシュを置けばサービスを経由しなくなりますが、その管理は必要になります。

何も変更していないのに、なぜ発生するようになったのですか?

レート制限は負荷に依存します。マトリックスの規模拡大、同時実行の増加、あるいは GitHub 側の混雑時期などが原因となり得ます。