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 is the quiet one
+Gradle treats a remote cache failure as non-fatal, so a 401 does not break the build and shows nothing at the default log level. The build just never uses the cache. Run with -i to see it. The usual causes are no credentials block, a password that did not reach Gradle's background daemon, or a typo. 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.
+ +