Caching Troubleshooting

Caching Troubleshooting

Common cache-related symptoms and how to fix them.

Step always runs (never cache hit)

Check artifact patterns

-- NOT cacheable:
step({ name = "x", phase = "p", scope = "s", run = "make" })

-- Cacheable:
step({ name = "x", phase = "p", scope = "s", input = { "src/**" }, output = { "build/app" }, run = "make" })

Check outputs exist

Step cache requires all recorded outputs on disk. If the binary is deleted, the step runs again.

Check --no-cache

beez build --no-cache   # intentional bypass

Check config

beez --show-config      # cache.enabled should be true

Step skipped but should have run

Stale index with wrong assumptions

Clear cache:

beez --clean-cache build

Input globs too narrow

If a dependency file is not matched by input or mutate, changing it will not invalidate the step. Widen globs or add explicit patterns.

Env var not in hash_vars

Toolchain change invisible to cache. Add vars to env.hash_vars.

Lua step not invalidating after build.lua edit

Lua callback steps fingerprint build.lua, not the callback body inline. Editing build.lua should invalidate. If you generate build.lua externally, ensure the file on disk updates.

Success cache never skips files

API not called

Success cache is opt-in. You must call ctx.file_success_cached() before work and ctx.cache_file_success() after success.

Config revision

Bump lint_rev (or similar) only when tooling changes, not on every edit.

get_cache_misses confusion

get_cache_misses() returns failures from the previous run at session start, not live state mid-loop.

Success cache skips but file was edited

file_success_cached compares file content hash and include tree. If it still hits:

• Confirm --no-cache is off
• Delete .cache/success/entries/ for that step
• Check that the path passed to the API matches the path from ctx.glob() (relative, forward slashes)

Lint checks everything after one failure

Expected: record_file_cache_miss adds paths to the misses file. Next run re-checks listed paths via get_cache_misses(). Other files can still skip if cached.

To force full re-lint:

beez --clean-cache

Or delete .cache/success/misses/<step>.misses.

Cache grows too large

• Run beez --update after switching compression to gzip with mode = always
• Delete .cache/ periodically in CI with a retention policy
• Success cache creates one manifest per cached file; very large projects may need occasional cleanup

Corrupt or unreadable cache file

Symptoms: errors mentioning cache file read/write.

beez --clean-cache

If compression settings changed radically, try beez --update first.

Parallel steps stomp files

Not a cache bug: overlapping mutate without proper order(). See Order Declaration and Parallel Execution and Dependencies.

Debugging checklist

1. beez --show-config - cache enabled, path, hash settings
2. beez build --verbose - look for cache hit lines (unless hide_cache_hits)
3. Inspect .cache/index/ for the step's index file
4. Run with --no-cache to confirm behavior without cache
5. Run with performance.cache_fs_metadata = false to rule out glob caching quirks

Related pages

• Caching Overview
• Step Cache
• Success Cache
• Cache Keys and Invalidation