Diagnosing Travis CI Cache Restoration Failures

Problem

Your Travis CI job reports that the cache was not restored, and dependencies are rebuilt from scratch each run, slowing the pipeline and potentially exceeding the 100 MB cache limit.

Recognizable Condition

In the Travis log you see lines similar to:

Restoring cache
Cache not found for key: your‑cache‑key
Saving cache

Even though a cache: section exists in .travis.yml, the restore step reports a miss and the save step either skips or finishes with an empty cache.

Cause & Diagnostic Table

Possible Cause	What to Look For
Cache key mismatch	The key expressed in .travis.yml (e.g., using checksums or branch names) differs from the key used when the cache was saved.
Directory not persisted	The paths listed under cache: directories do not exist, are empty, or are not writable during the job.
Concurrent job interference	Multiple builds with the same cache key run in parallel, causing one job to overwrite another's cache.
Cache size limit exceeded	The cached directory exceeds Travis' 100 MB limit; the save operation fails silently and appears empty on restore.

Ordered Checks

1. Verify the cache key

   Open the job log and locate the line that prints the key being used for restore, e.g., Restoring cache for key: linux‑node‑14‑package-lock‑…​. Compare this string to the key expression in .travis.yml. If they differ, the key is mismatched.

   Where to run: Travis UI → Job → Logs. No special permissions needed.

2. Inspect the cached directories

   Add a temporary script step before the cache restore to list the target directories:

   before_cache:
     - ls -la $HOME/.npm
     - du -sh $HOME/.npm
   

   Check the log output for existence and size. If the directory is missing or zero‑size, the cache cannot be saved.

3. Check for concurrent jobs

   In the Travis UI, view the build matrix for the commit. If multiple jobs share the same cache key and run concurrently, note overlapping timestamps.

4. Measure cache size

   After a job finishes, open the job page and look for the "Cache" section. It reports the size of the saved cache. If it shows "0 B" or is absent, the save likely failed due to size limits.

Fixes Tied to Findings

• Key mismatch

  Ensure the key expression is deterministic and identical across save and restore. A common pattern:

  cache:
    directories:
      - $HOME/.npm
    key: ${{ checksum \"package-lock.json\" }}-{{ arch }}-{{ os }}

  Avoid using volatile values like the current timestamp or $TRAVIS_BUILD_NUMBER in the key.

• Directory not persisted

  Make sure the directory exists before the cache step. Add a preparatory step:

  install:
    - npm ci
  before_cache:
    - mkdir -p $HOME/.npm
  

  Also verify that the user running the build has write permission to the path (the default Travis user does).

• Concurrent job interference

  Scope the cache key to the job or include a matrix attribute:

  key: ${{ checksum \"package-lock.json\" }}-{{ os }}-{{ env }}

  If you intentionally want a shared cache, serialize the jobs using stages or limit concurrency via repository settings.

• Cache size limit exceeded

  Prune unnecessary files before caching. For Node.js, you can exclude large modules:

  cache:
    directories:
      - $HOME/.npm
    # optional: skip large packages
    before_install:
      - npm prune --production
  

  After pruning, re‑run the job and confirm the reported cache size stays under 100 MB.

Escalation Criteria

• After applying the above fixes, the cache still reports "Cache not found" for three consecutive builds.
• The cache size consistently exceeds 100 MB despite pruning, indicating a need for external artifact storage (e.g., S3, GitHub Packages).
• Logs show intermittent permission errors on the cache directory that cannot be resolved by adjusting before_cache steps.

If any of these conditions occur, open a support ticket with Travis CI, providing the job ID, the relevant .travis.yml snippet, and the log excerpts showing the cache miss and any error messages.

Limitations and Practical Verification

This guide covers the most frequent causes of cache restoration failures in Travis CI. It does not address edge cases such as custom storage drivers or network‑level timeouts, which would require deeper log inspection. To verify that a fix works:

1. Trigger a rebuild after changing .travis.yml.
2. In the job log, confirm the line Restoring cache for key: … is followed by Cache restored (or a similar success message).
3. Check the "Cache" section of the job UI for a non‑zero size.
4. Optionally, run a local script that mirrors the cache directory and compare file counts before and after the build to ensure persistence.