Gradle build cache HTTP status codes: 401, 403, 404 and 413
Gradle talks to the cache with plain web requests, and it does not fail the build when the cache says no. So the status code is often the only clue. This is what each one means for a FosterStack Cache server.
The short table
| Status | When you get it | What to do |
|---|---|---|
| 200 | A stored entry was found and sent. | Nothing. This is a cache hit. |
| 201 | An upload was stored. | Nothing. |
| 404 | That key is not stored. | Usually nothing. It is a cache miss. With a correct password it means the key just is not there yet. |
| 401 | No password, or the wrong one. | Fix the credentials block. See below. |
| 403 | A write sent with the read-only login. | Use the read-write login for machines that upload, or set the client not to upload. |
| 413 | An upload bigger than the server's size limit for one entry. | Raise FSCACHE_MAX_BODY_BYTES if the entry is meant to be cached. |
Tested on a real server
These were all run against a 0.2.1 server started with a read-write login, a read-only login, and the body limit set to 1024 bytes. Your numbers for the limit will differ, since the default is 1 GiB.
GET /healthz (no credentials) 200
GET /metrics (no credentials) 200
GET key, no credentials 401
GET key, wrong password 401
GET missing key, read-write login 404
PUT 5 bytes, read-write login 201
GET stored key, read-write login 200
GET stored key, read-only login 200
HEAD stored key, read-only login 200
PUT, no credentials 401
PUT, read-only login 403
PUT 2048 bytes (limit set to 1024), read-write login 413
GET the too-large key afterwards 404
/statusz, no credentials 401The health and metrics paths stay open without a password, so monitoring works. The status page does not.
401 does not break the build
Gradle treats a remote cache failure as non-fatal, so a 401 does not fail the build. The build just runs without the cache. In our test with Gradle 9.8.0 on macOS it printed this at the default log level:
Could not load entry d4f2de693b561fd2c5d60b17a9232d6f from remote build cache: Loading entry from 'http://127.0.0.1:18099/d4f2de693b561fd2c5d60b17a9232d6f' response status 401: UnauthorizedThe usual causes are no credentials block, a wrong password, or a typo. Run with -i for more detail. To test the server directly:
curl -s -o /dev/null -w '%{http_code}\n' -u gradle:wrong-password https://cache.example.com/some-keyA 401 here means the credentials are wrong. A 404 means they are right and the key simply is not stored. More steps are in Gradle remote build cache not working.
403 means the login worked but may not write
The server can have an optional read-only login. A client holding it can read (GET and HEAD return 200 as normal) but any write gets a 403. That is the intended way to give laptops a cache they can read and not change. See who can write to a remote build cache.
413 and entry size
A single upload over the limit is refused with 413 and nothing is stored, so a later request for that key is a 404. The limit is FSCACHE_MAX_BODY_BYTES and defaults to 1 GiB per entry.
Related: server sizing and monitoring.