Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

GET /chunks returns 500 "read chunk failed" where /bytes and /feeds return 404

Open
  • Is something wrong?
#5,624 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

  • #1 by @Saadanjum0 — closed without merging
  • #5642 by @Saadanjum0 — closed without merging

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
go, openapi
Domain
backend-api-design

Research direction

Trace the /chunks/{address} handler and its retrieval error mapping, then compare the /bytes and /feeds handlers and the OpenAPI response documentation. Start by locating these API entry points and the relevant tests; run the endpoint tests to establish current behavior. Done means missing chunks and retrieval failures have distinct documented status codes, with tests covering the cases.

Written by the indexing model from the issue text.

Description

accepted seen

Summary

GET /chunks/{address} answers 500 read chunk failed for a chunk the node cannot produce, where GET /bytes/{reference} and GET /feeds/{owner}/{topic} answer 404 for the equivalent condition. A 500 tells every HTTP client that the server is broken; here it usually means "I looked and did not find it", which a client should handle quite differently.

This is about which status code carries which meaning. It is not a request for Bee to prove that a chunk does not exist — see "What we are not asking for" below.

Observed

Bee 2.8.2 (2.8.2-7e703f4, API 8.1.1), a local bee-factory cluster:

Request Condition Response
GET /bytes/{ref} never uploaded 404
GET /feeds/{owner}/{topic} feed has no updates 404 {"code":404,"message":"lookup at failed"}
GET /chunks/{addr} never uploaded 500 {"code":500,"message":"read chunk failed"}
GET /chunks/{addr} uploaded moments ago, not yet retrievable 500 {"code":500,"message":"read chunk failed"}
GET /chunks/{addr} uploaded, settled (about a second later) 200 
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:1633/bytes/efef...efef
404
$ curl -s -w '\n%{http_code}\n' http://127.0.0.1:1633/feeds/19e7...ff2a/cdcd...cdcd
{"code":404,"message":"lookup at failed"}
404
$ curl -s -w '\n%{http_code}\n' http://127.0.0.1:1633/chunks/abab...abab
{"code":500,"message":"read chunk failed"}
500

Why it matters to a client

A client library cannot map these onto sensible behaviour without string-matching the message:

  • 404 → the thing is not there; carry on, perhaps write it.
  • 500 → the server is in trouble; surface an error, back off, do not treat this as data.

Because /chunks returns 500 for the ordinary "not found" case, a library must either treat some 500s as absence (and risk swallowing a real fault) or treat every 500 as a fault (and break on a perfectly normal missing chunk). We are writing an SDK that reads feed updates by index, where "no update at this index yet" is the expected answer most of the time, and we had to match on read chunk failed to get either behaviour right.

It is also inconsistent within Bee's own API: three endpoints, one underlying condition, two status codes.

Suggested

Distinguish what the node actually knows:

  • 404 — retrieval completed and the chunk was not found. Matches /bytes and /feeds.
  • 504 (or 503) — the retrieval attempt did not complete: timed out, no peers, upstream error.
  • 500 — an internal error in the node itself.

The OpenAPI spec would need the same change, since it currently documents 404 for /chunks while the implementation returns 500.

What we are not asking for

Not a guarantee of absence. In a distributed store no node can prove a chunk was never written, and a 404 here would rightly mean "I did not find it", not "it does not exist". Clients that need "is this address free" have to solve that themselves, and we are doing so. The ask is only that "I looked and found nothing" and "something went wrong" stop sharing a status code.

One thing we have not pinned down

Immediately after an upload the same address answers 500 for roughly a second and then 200:

+0ms     chunk=500  feed=404
+1000ms  chunk=200  feed=200

Some addresses were readable at once and others were not, which makes us suspect it depends on whether the chunk's neighbourhood is the receiving node's own — that is, ordinary push-sync latency rather than a fault. We are not reporting that as a bug. It is relevant here only because it is another case that arrives as the same 500, and a client cannot tell it from a chunk that was never written.

Environment

Bee 2.8.2 (2.8.2-7e703f4, API 8.1.1) in a local bee-factory cluster, queen on 127.0.0.1:1633, immutable depth-20 batch on the dev chain. Seen from both @ethersphere/bee-js 13.0.0 and plain fetch.

Dominant language
Go
Stars
1.5k
Forks
390
Avg merge
4d 15h
Merged PRs (30d)
21

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ethersphere/bee

All issues in ethersphere/bee

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.