Documentation menu
Documentation

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 401 is 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_SERVER must 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's url and 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 requires org.gradle.caching=true and 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": true in nx.json, that both Nx environment variables are visible to the lerna process, 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 isPush is 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 --info output: a 401means 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.dev with no path, org.gradle.caching=true is set (or --build-cache is passed), the task is cacheable, and GRADLE_CACHE_TOKEN is exported in the environment Gradle runs in. Run with --info and look for FROM-CACHE.
Bazel never hits the cache
Confirm --remote_cache is the bare host with no path - Bazel appends /ac/ and /cas/ itself. Check the --remote_header token is present and not revoked. Remember the committed .bazelrc in 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.

Get back to fast builds
Most of these are a one-line fix. The dashboard shows whether it worked.
Start freeSee pricing