GitHub Actions "cache key contains invalid characters"

Cache keys must avoid certain reserved characters - notably commas, which separate restore-keys, and control characters. A key containing them is rejected before any cache operation runs.

What this error means

A cache step fails validation because the key contains disallowed characters.

github-actions

Error: Key Validation Error: ${{ matrix.os }},node-20 cannot contain commas.
Cache key contains invalid characters.

Common causes

Comma in the key

Commas are reserved as the restore-keys separator and are not allowed inside a single key.

Newlines or control characters

A key built from multiline content can include disallowed characters.

How to fix it

Sanitize the key

Replace commas with hyphens or another safe separator.
Trim newlines; build keys from single-line, predictable values like hashFiles.

.github/workflows/ci.yml

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

How to prevent it

Compose keys from os, a label, and hashFiles - no commas.
Avoid interpolating raw multiline content into keys.

Related guides

GitHub Actions Cache Never Hits - Key Changes Every RunFix an actions/cache that never restores because the key is non-deterministic - hashing a generated file, the… GitHub Actions cache key changes every run (never hits)Fix a GitHub Actions cache that never hits because the key includes a value that changes on every run, such a… GitHub Actions Cache Key Collision Across Branches Restores Wrong CacheFix GitHub Actions caches bleeding across branches - a key without a branch or lockfile component lets one br…