arrivals-and-departures-for-stop: keep returning an empty entry on no-service days (Java returns bare `null`)

Open Beginner friendly
#2,102 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

@chikolavosaki-sys is already working on this.

Since Nov 16, 2026.

  • #2104 by @chikolavosaki-sys — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
64/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
go

Research direction

Start from TestArrivalsAndDeparturesForStopHandlerNoActiveServices and the arrivals-and-departures-for-stop handler it exercises; note how the existing test picks a date past every calendar's end. Then find where the repo records Java-parity deviations (search for existing "parity" or "deviation" notes) and add an entry there. Done means the deviation is written down and a new fixture whose only route has a calendar excluding the query day, while other routes are active, returns code: 200 with an empty arrivalsAndDepartures.

Written by the indexing model from the issue text.

Description

Summary

On production Puget Sound (Java OBA 2.5.53-cs), arrivals-and-departures-for-stop sends back HTTP 200 with a 4-byte body that just says null (Content-Type: application/json) for a stop with no service on the requested day (seen at 1_39810; I haven't surveyed other stops). Maglev returns a normal response for the same case: code: 200, the stop, empty arrivalsAndDepartures, nearbyStopIds, and references to the routes that serve the stop. TestArrivalsAndDeparturesForStopHandlerNoActiveServices covers this.

This is one place where maglev should not copy Java. This issue records why, so that later parity work doesn't "fix" maglev to match Java's behaviour.

What happened

The iOS app showed riders this error for stop 1_39810 (California Ave SW & SW Myrtle St, Seattle) on a Sunday evening:

Decoder failed for https://api.pugetsound.onebusaway.org/api/where/arrivals-and-departures-for-stop/1_39810.json: endpoint returned the string 'null' instead of a real value.

Only one route serves this stop: 1_100111 (Route 22), and it runs on weekdays only. Results from probing with time=:

Requested time Java response
Mon 2026-11-16 08:00 PT normal arrivals
Mon 2026-11-16 03:00 PT (a service day, before the first trip) valid entry, arrivalsAndDepartures: []
Sun 2026-11-15 22:00 PT null
Sat 2026-11-21 12:00 PT null
Sun 2026-11-22 12:00 PT null

So Java handles "no trips in this window" correctly, and fails only when no route at the stop has an active service date. The other stops on Route 22 that I tested also have routes that run on weekends, and they return normal responses. stop/1_39810.json works, and on Sunday schedule-for-stop returns stopRouteSchedules: []. I added a cache-busting query parameter to rule out a stale CloudFront response, and the result was the same.

Reproduce: curl 'https://api.pugetsound.onebusaway.org/api/where/arrivals-and-departures-for-stop/1_39810.json?key=TEST' on a Saturday or Sunday. Any day works if you add a weekend time= value.

Why Java does this

A bare null body is what Struts' ModelDriven serializer writes when the action unwinds without setting _response. That's the same mechanism as OneBusAway/onebusaway-application-modules#461 (SDMTS Blue Line). There, a stop→route-collection reference that didn't resolve to a RouteBean on the service date caused an NPE in BeanFactoryV2.getStop(), outside the action's try. Commit 801de7b82 fixed that path in 2.7.2. Puget Sound runs 2.5.53-cs, which predates the fix. The pattern here (the stop's only route has no service that day) fits the same "route doesn't resolve on this service date" cause. I haven't confirmed that from the PS logs.

Even on a patched Java server, this case would return an exception envelope (an error), not an empty entry. "Matching Java" therefore means returning either null or an error here, and neither is correct.

A bare null doesn't always mean "no service"

The same body has two causes, and only one of them is "no buses today":

  • No service on the day (this report): the stop is fine, and nothing runs there that day.
  • A crash while building the reply (#461): at SDMTS, broken route data made the serializer fail, and most Blue Line stations returned null while trains were running.

So this issue does not ask maglev to treat failures as empty results. The correct deviation from Java is narrow:

  • When the stop exists and no route serving it has an active service date, return code: 200 with an empty arrivalsAndDepartures, as maglev does now.
  • When building the reply fails (an unresolvable route, a DB error, a bad bundle record), return an error envelope with a 5xx code, as serverErrorResponse does now. Never return an empty entry for that case: it would tell riders nothing is coming when service is running, which is worse than an error.

Why maglev's behaviour is the right one

  1. "No service today" is a valid answer, not an error. Weekday-only, school-day-only and seasonal stops are common. A rider who opens one on a weekend should see "no departures", not a failure. Java already returns an empty entry when the window is empty on a service day. Whether the day has any service shouldn't change the shape of the response.
  2. A bare null with HTTP 200 breaks the API contract. The body is valid JSON, so it gets past content-type checks. But it has no code, text, version or data, so clients can't tell it apart from a server crash. Every OBA response is supposed to be the {code, currentTime, text, version, data} envelope.
  3. Clients need the stop and route references to render the screen. Maglev's empty response still carries the stop, its routes, nearbyStopIds and situations. With that, a client can show the stop header, alerts and nearby stops along with an empty list. Neither a null body nor an error envelope gives the client anything to draw.
  4. Java itself treats the bare null as a bug. See OneBusAway/onebusaway-application-modules#461 and 801de7b82. Copying it would mean copying a defect.

Ask

  • Keep the current behaviour. Record it as an intentional deviation wherever maglev tracks Java-parity exceptions, so a parity audit against a pre-2.7.2 server doesn't flag it.
  • Consider adding a test case modelled on this one: a stop whose only route has a calendar that excludes the query day, while other routes in the feed are active that day. The existing test uses a date past every calendar's end, which covers "nothing active anywhere" but not "nothing active at this stop".

Client side: OneBusAway iOS is adding a fallback for servers that still return null here. It loads the stop separately. If the stop exists, the app shows its usual neutral empty state ("No departures in the next N minutes"), not "no service today", because a null can't tell it which cause it's seeing. It also logs the null at error level, so server-side failures stay visible.

Dominant language
Go
Stars
57
Forks
113
Avg merge
5d 13h
Merged PRs (30d)
151

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 OneBusAway/maglev

All issues in OneBusAway/maglev

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.