Depot Cache auth: user tokens, org tokens, and the X-Depot-Org gotcha
Shows how to fix depot Cache auth: user tokens, org tokens, and the X-Depot-Org gotcha. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Use the right one and set the org header. [Depot docs]: Depot Cache accepts user tokens and organization tokens; project tokens are NOT supported for cache because only container builds use projects.
Steps
- [Depot docs]: Depot Cache accepts user tokens and organization tokens; project tokens are NOT supported for cache because only container builds use projects. User tokens come from your user settings page, org tokens from the org settings page. If you use a user token and belong to more than one organization, set the X-Depot-Org header (or org context per integration) to your Depot org ID or cache writes land in the wrong place. Depot GitHub Actions runners are pre-configured with a short-lived DEPOTCACHETOKEN per job and need no manual setup.
When to use
You are seeing this: User tokens come from your user settings page, org tokens from the org settings page. Use this skill when you run into "Depot Cache auth: user tokens, org tokens, and the X-Depot-Org gotcha".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.