A Jira endpoint that under-reports, and why we read schemes one at a time

What we saw

Our app reported a group as clear for notification schemes. Jira's own admin UI showed the same group attached to two events on a scheme called Engineering Notifications. The app was wrong, and it was wrong in the worst possible direction: it told someone a change was safe when it wasn't.

The list call returned all three schemes on the site. Two came back with full event lists. One came back empty:

scheme="Default Notification Scheme"      events=16
scheme="Engineering Notifications"        events=0   <- has 2 events in the UI
scheme="KAN: Simplified Notification..."  events=11

Same request, same expand=all, same response body. One scheme silently lost its events while its neighbours kept theirs.

Why this is not a parsing bug

That was our first assumption, and it was wrong. If we were mishandling the shape of the response, all three schemes would have come back empty. Two of them parsed correctly through exactly the same code path. The array notificationSchemeEvents was present and empty on the wire.

We have not established the underlying cause, and we are not going to guess at one in public. What we can say precisely is the observable behaviour: the list endpoint's expansion is not reliable per scheme, and nothing in the response tells you which schemes you can trust.

The fix

List the schemes, then read each one individually:

GET /rest/api/3/notificationscheme/{id}?expand=all

The detail call returns the real events. It costs one extra request per scheme, and the number of notification schemes on a site is small, so the cost is not interesting. Trusting the answer is.

We also changed what happens when a detail call fails. Previously a scheme that couldn't be read was quietly omitted, which looks identical to a scheme with nothing in it. Now the whole section reports not checked. A gap you can see is a different thing from a gap you can't.

Reproducing it

1. Create a notification scheme and attach a group to at least one event.
2. Call GET /rest/api/3/notificationscheme?expand=all.
3. Compare notificationSchemeEvents for your scheme against what the admin UI shows.
4. Call GET /rest/api/3/notificationscheme/{id}?expand=all for the same scheme and compare again.

We could not find an open Atlassian ticket describing this specific behaviour. The nearest one we found, JRACLOUD-76368, concerns missing identity details on custom-field notifications and was resolved in 2021 — related area, different defect. If you know of an existing report, we would like the link.

Why we are writing this down

Any tool that reads notification schemes from the list expansion has this false negative, and by construction it has no way to know. The failure is silent on both sides: the API doesn't flag it, and the tool reports a clean result. If you have built something on that endpoint, it is worth ten minutes to check.

It is also the reason we are fussy about the difference between clear and not checked. A tool that tells you a change is safe when it simply couldn't see is worse than having no tool, because you act on it. This bug was ours for two days before we caught it, which is exactly how long it takes for that kind of answer to become someone's outage.

Get in touch

Corrections, a case we've got wrong, or a link to a prior report — we'd rather hear it. hello@lintelworks.net