Troubleshooting

Work through the checks

Start with the CLI's own checks, then narrow the problem to repo config, one adapter run, or access scope before contacting support.

1. 01

   Check the connection

   Doctor checks the configured API, resolved workspace, restore/save/admin capabilities, command readiness, and the workflow trust contract.

   Use --json in CI when you need machine-readable evidence.

   boringcache doctor
   boringcache doctor --json

2. 02

   Review the repo plan

   Audit finds cache usage in the repository and shows entries or profiles missing from .boringcache.toml.

   Run it read-only first. Use --write only after the proposed entries match the paths and commands you intend to cache.

   boringcache audit
   boringcache audit --json

3. 03

   Reproduce one cache path

   Run the same tool-named adapter and build command outside the larger workflow. Verbose CLI output shows the adapter setup; verbose Action diagnostics also includes bounded proxy logs.

   Keep the failing command, workspace, platform, and trust level the same while comparing local and CI behavior.

   Local adapter

   boringcache --verbose gradle

   GitHub Actions

   with:
     diagnostics: verbose

4. 04

   Check the Workspace outcome

   Start with status for the Workspace picture. Use check for the exact expected tags, then inspect only a named Cache entry that needs deeper storage or lifecycle detail.

   Confirm that local and CI resolve the same Workspace and compatible cache identity. Open the Workspace in the app to compare sessions, hits, repeat misses, writes, and the job that produced them.

   Workspace to Cache entry

   boringcache status my-org/app
   boringcache check my-org/app deps --json --fail-on-miss
   boringcache inspect my-org/app deps

5. 05

   Send a focused support report

   If the problem remains, send the CLI version, failing command, tool and platform, CI job URL or approximate run time, and reviewed doctor output to support@boringcache.com.

   Remove credentials, signed URLs, source text, and unrelated environment variables before sending diagnostics.

   Email support →

Do not paste tokens, signed object URLs, or complete environment dumps into an issue or support message.

Start from the symptom

Use the shortest check that matches what failed.

Cache never hits

Compare workspace, tag, platform and git scope, then inspect repeat misses for the exact adapter session.

Open adapter guides →

Restore works, publish does not

Check Doctor's save capability and the job's trust policy. Restore-only pull requests are expected to skip publication.

Review authentication →

Local and CI behave differently

Compare the resolved workspace, OS and architecture, toolchain, command, and any physical-path constraint such as Xcode checkout and DerivedData paths.

Compare adapter requirements →

Artifact upload or download fails

Check Artifact permissions and retention separately from cache. Re-run the exact artifact command with --verbose.

Open Artifact docs →

Docker rebuilds or misses

Inspect the BuildKit solve and adapter diagnostics first. Layer cache, persistent cache mounts, and native tool cache are separate reuse paths.

Open the Docker adapter →

BYOC or storage access fails

Run the storage verification for the configured provider and check bucket identity and permissions without sharing credentials.

Verify BYOC storage →