GitHub Actions "cache key contains invalid characters"

By Daniel Zoghalchali·Latchkey

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.

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

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

- 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.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions