Documentation menu
Troubleshooting cache errors
Find the symptom, not the tool. Most cache failures are one of four things: a URL with a path appended, a token with the wrong scope, a task that was never cacheable, or environment variables that did not reach the process that needed them.
Diagnose and fix a specific cache error
What the status codes mean
- 401 Unauthorized
- The token is missing, invalid, revoked, or scoped to a different workspace. Generate a new one under your workspace's tokens. A
401is always about the credential - it never means the artifact is absent. - 403 Forbidden on upload
- Your token is read-only. Downloads work and uploads are rejected. That is the intended configuration for pull-request and fork builds; use a read-write token for the builds that should populate the cache, typically your protected branches. See tokens and access control.
- 404 Not Found
- Usually just a miss: no artifact exists for that task hash yet, so the build runs the task and (with a read-write token) populates the cache for next time. If every lookup misses, check the configured URL, workspace, whether a trusted writer has populated it, and whether the clients compute matching keys. The appended-path mistake below is one possible cause, not proof that a cache is broken.
- 409 Conflict
- An Nx upload tried to replace an immutable entry. In a race between equivalent producers, check that the existing entry restores correctly before treating the rejected duplicate as harmless. A 409 does not establish that the earlier artifact is correct. Turborepo, Gradle and Bazel CAS acknowledge duplicate writes as successful without replacing the artifact; Bazel action-cache records can be replaced. See the protocol-specific trust model.
- 413 Payload Too Large
- The artifact exceeds an upload-size limit. The managed endpoint currently has a 100 MB infrastructure ceiling per request, which can reject an upload before Cachely runs or records activity. The rejected attempt does not store an artifact. Check the compressed upload size and your task's output configuration; increasing a timeout does not raise this ceiling. See artifact upload limits for all tools. A build can still finish successfully after an upload fails. Gradle may also disable remote caching for the remaining build; see the Gradle disabled-cache guide.
Nothing ever hits the cache
- Every request 404s (Nx)
NX_SELF_HOSTED_REMOTE_CACHE_SERVERmust be the bare host (https://remote.cachely.dev) with no trailing path. Nx appends/v1/cache/<hash>itself, so adding it yourself doubles the path and nothing is ever found. The same rule applies to Gradle'surland Bazel's--remote_cache.- Requests succeed but always miss
- Different machines are computing different task hashes. The usual cause is an Nx version mismatch between CI runners and developers - hashes are not comparable across versions, so the cache is technically working and structurally useless. Pin the version. If Nx versions match, use the Nx inputs and outputs diagnosis to inspect the resolved target and test which changes invalidate it. For other tools, the hit-rate guide covers inputs and environment drift.
- The task is not cacheable
- Nx and Lerna only consult the cache for targets declared cacheable in
nx.json("cache": true). Gradle requiresorg.gradle.caching=trueand a task type that supports output caching. - The variables never reached the build
- Environment variables set on one CI step are invisible to the next. Declare them at the workflow or job level. Locally, confirm the shell that runs the build actually exports them - a variable set in a different terminal tab is the most common version of this.
Tool-specific symptoms
- Turborepo reports a cache hit but dist is missing
- Cached logs can replay when the entry contains no build files. Follow the missing outputs guide to check the task's globs and verify that the next step can read the restored files.
- Lerna runs but never hits the remote cache
- Confirm the task has
"cache": trueinnx.json, that both Nx environment variables are visible to thelernaprocess, and that every runner resolves the same Nx version. Lerna delegates cache reads and writes to Nx, so every Nx cause applies unchanged. - Gradle loads but never stores
- If stores are skipped, check whether
isPushis false or the token is read-only. Both are the intended CI-push / developer-read configuration - check whether this build is meant to be a writer. If a store is attempted, inspect--infooutput: a401means the token is wrong or revoked, while a 413 means an upload-size limit rejected the entry. - Gradle never stores or loads anything
- Confirm the URL is
https://remote.cachely.devwith no path,org.gradle.caching=trueis set (or--build-cacheis passed), the task is cacheable, andGRADLE_CACHE_TOKENis exported in the environment Gradle runs in. Run with--infoand look forFROM-CACHE. - Bazel never hits the cache
- Confirm
--remote_cacheis the bare host with no path - Bazel appends/ac/and/cas/itself. Check the--remote_headertoken is present and not revoked. Remember the committed.bazelrcin the Bazel setup disables uploads by default, so a workspace where only developers build will stay empty until trusted CI runs with--config=cachely-ci.
The dashboard shows no activity
Either no cache requests have arrived in the selected time range, or the token used belongs to a different workspace than the one you are viewing. Widen the range first - it is the cheaper check. If a full CI pipeline produced nothing at all, the variables did not reach the build; see CI setup.
Still stuck
Ask in the Cachely Discord - someone has usually hit the same status code - or email hello@cachely.dev with the build tool and version, the status code you are seeing, and whether the token is read-only or read-write. Either way, do not post or send cache artifacts or build logs containing your source paths - we do not need them and do not want them, and Discord is a public channel.