Cache Problems

Cache Miss on First Build

Symptom: First build of a new app or branch shows “cache miss” in logs.

Cause: This is expected behavior. There is no cache available yet because:

This is the first build of the branch or app
Cache was cleared or expired (14-day age limit)

Solution:

No action needed. Subsequent builds will use the cache. The first build:

Installs all dependencies
Saves them to cache
Future builds restore and reuse them

After the first build, you should see “cache hit” in subsequent builds (assuming the lock file hasn’t changed).

Cache Not Restoring

Symptom: Build takes as long as the first build even though cache was hit before. No cached dependencies are being reused.

Cause: The cache key changed because:

Lock file updated (e.g., Podfile.lock, Package.resolved) — This is the most common cause
You switched branches or changed build configuration
Cache was manually cleared

Solution:

Verify the lock file changed:
- If you ran pod update or swift package update, the lock file changes
- This is expected—a new lock file means new dependencies, so the cache doesn’t apply
Regenerate cache with new lock file:
```
steps:
  - name: Install dependencies
    run: pod install
```
This will create a new cache with the updated lock file. Subsequent builds will use it.
To use the previous cache, revert the lock file:
Terminal window
```
git checkout HEAD -- Podfile.lock
```
To prevent accidental lock file changes:
- Commit your lock files to version control
- Use pod install (not pod update) to use locked versions

Cache Size Exceeded

Symptom: Cache hits slow down or build fails with cache error.

Cause: Total cache size for your agent has exceeded 50GB limit.

Solution:

Clear cache manually:
- Go to App Settings > Cache (or Settings tab)
- Click Clear Cache
- This deletes all cached dependencies
- Next build will re-download and re-cache
Optimize dependencies:
- Remove unused pods or Swift packages
- Use lightweight alternatives
- Example: Remove SwiftLint from production dependencies if it’s only needed for CI
Monitor cache size:
- Dashboard may show current cache size
- Run builds and monitor which dependencies take the most space
- Remove the largest unnecessary ones
For mono-repos:
- If you have many apps in one workspace, each app gets its own cache
- Very large repos may hit the 50GB limit faster
- Consider splitting into separate workspaces if needed

Cache Eviction

Symptom: Builds older than 14 days are slower again (cache was evicted).

Cause: RunnerHub automatically evicts cache entries older than 14 days to manage storage.

Solution:

No action needed. If you’re actively building on a branch, the cache is refreshed regularly and won’t be evicted.

To keep cache fresh:

Build regularly on your branch
Or manually clear and rebuild cache before it expires

DerivedData Cache Per Branch

Symptom: Building on different branches seems to lose cached data.

Cause: Xcode’s DerivedData is cached per branch. When you switch branches:

New branch gets a fresh cache
Old branch cache is retained (for 14 days)

Solution:

This is expected behavior and helps isolate builds per branch. Each branch builds independently, which is good for safety.

If you want all branches to share cached dependencies:

Use lock files (Podfile.lock, Package.resolved)
These are shared across branches via git
Dependencies are cached based on lock file hash, not branch name

How to Clear Cache

From Dashboard

Go to App > Settings
Find the Cache section
Click Clear Cache or Delete
Confirm the action
Next build will start fresh

Automatic Cache Clearing

Cache automatically clears when:

14 days pass since last use
Agent’s total cache exceeds 50GB (oldest entries evicted first)
You manually clear it from the dashboard

Cache Hit vs. Miss

In your job logs, you’ll see:

Cache Hit:

Restoring cache for com.example.myapp-ios-v1...
Cache restored: 1.2GB in 15 seconds

Cache Miss:

Cache miss for com.example.myapp-ios-v1
Downloading and installing dependencies...

Cache Miss (Expired):

Cache expired (older than 14 days)
Downloading and installing dependencies...

Debugging Cache Issues

1. Check the Cache Key

The cache key is based on:

App name and platform
Lock file contents (Podfile.lock, Package.resolved, etc.)
Branch (optional, if configured)

If the lock file changes, the cache key changes, and you’ll get a cache miss.

2. View Cached Files

You can’t directly view cached files, but you can infer what’s cached by:

Looking at your dependency files (Podfile, Package.swift, etc.)
Checking the cache size in the dashboard
Reviewing build logs for “restoring cache” messages

3. Force Cache Refresh

To force a fresh build without cache:

Clear cache from dashboard
Or update your lock file (pod update, swift package update)
This creates a new cache key, forcing a fresh build

Best Practices

Commit lock files to git:
- Podfile.lock (CocoaPods)
- Package.resolved (Swift Package Manager)
- These ensure consistent, cacheable builds

Use install instead of update:

- name: Install dependencies
  run: pod install  # Uses Podfile.lock

Instead of:

- name: Update dependencies
  run: pod update  # Always updates, invalidates cache

Clear cache when needed:
- If dependencies become corrupted
- If cache is consuming too much space
- Otherwise, let it work automatically
Monitor cache effectiveness:
- Review job logs for “cache hit” vs “cache miss”
- Identify patterns (e.g., cache miss every 14 days = automatic expiry)
- Optimize accordingly

Getting Help

If cache issues persist:

Verify your lock files are committed to git
Check that your dependency files haven’t changed unexpectedly
Clear cache and rebuild to verify the issue
Review job logs for exact cache behavior
Contact RunnerHub support with your app’s cache configuration