GitLab CI "cache:key:files config requires at least one file"

By Daniel Zoghalchali·Latchkey

cache:key:files derives a cache key from the SHA of up to two files, so the cache invalidates when those lockfiles change. It must list at least one and at most two files.

What this error means

CI lint rejects the cache config, stating cache:key:files requires at least one file, or that too many files were provided.

This GitLab CI configuration is invalid:
jobs:build:cache:key:files config requires at least one and no more than two files

Common causes

Empty files list

A files: [] or a files: key with no entries provides nothing to hash.

More than two files listed

cache:key:files accepts a maximum of two file paths.

Listed file path does not exist

If neither listed file exists, GitLab falls back to a default key but the config intent is broken.

How to fix it

List one or two real lockfiles

Point cache:key:files at the lockfiles that should invalidate the cache.

build:
  cache:
    key:
      files:
        - package-lock.json
        - yarn.lock
    paths:
      - node_modules/

How to prevent it

• Always list at least one existing lockfile under cache:key:files.
• Keep the list to two files maximum.
• Pair cache:key:files with a prefix if you share caches across jobs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation