Turborepo remote cache "401 unauthorized" in CI

By Kaveh Alemi·Latchkey

Turbo tried to reach the remote cache and the server returned 401. The TURBO_TOKEN is missing or invalid, or the TURBO_TEAM slug does not match the token, so authentication fails and caching is skipped.

What this error means

The run logs a remote cache error such as "401" / "unauthorized" or "failed to contact remote cache", and tasks fall back to running locally without cache hits.

x failed to fetch artifact from remote cache: 401 Unauthorized

Common causes

Missing or invalid TURBO_TOKEN

No token is set in the environment, or the value is expired or revoked, so the remote cache rejects the request.

TURBO_TEAM does not match the token

The team slug points at a workspace the token cannot access, producing a 401 even though the token is valid elsewhere.

How to fix it

Set TURBO_TOKEN and TURBO_TEAM from secrets

1. Store the remote cache token as a CI secret.
2. Set TURBO_TOKEN and TURBO_TEAM in the job environment.
3. Re-run so Turbo authenticates to the cache.

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Confirm the team slug matches the token

Ensure TURBO_TEAM is the slug the token is authorized for, or use --api/--token flags consistent with a self-hosted cache.

How to prevent it

• Keep TURBO_TOKEN in CI secrets and rotate it on a schedule.
• Match TURBO_TEAM to the token's workspace.
• Treat remote cache 401s as auth, not network, failures.

Frequently asked questions

Related guides

References

• GitHub Actions documentation