2026-07-17 · 6 min read · Rahul Chitturi
- json
- api
- debugging
Cursor pagination bugs usually appear as missing rows, repeated rows, or a list that stops early even though more data exists. The visible issue is a frontend table, but the cause can live in the API response shape, sort order, encoded cursor, or retry behavior.
Start with two adjacent responses from a safe environment or a sanitized production sample. Format the JSON so the items, next cursor, previous cursor, total hints, and sort fields are visible before you change API code.
Trace the cursor as data
A cursor is often an opaque string, but it still has a contract. It may wrap an ID, timestamp, compound sort key, page direction, or tenant boundary. If that contract changes during a rollout, clients can skip or repeat records without throwing a syntax error.
- Compare the last item on page one with the first item on page two
- Decode Base64 cursors only when they are designed to be inspectable
- Check whether timestamps use seconds, milliseconds, or ISO strings
- Confirm retries reuse the same cursor instead of advancing state twice
Separate ordering from transport bugs
Pagination should use a stable sort. If records share the same createdAt value, include a tie-breaker such as ID so the API can produce deterministic pages. Without that, new inserts and retries can move items across page boundaries.
Diff a known-good response against the failing response after redacting user data. Preserve array lengths, null versus missing fields, cursor strings, and sort values so reviewers can see whether the contract or the data changed.
A Flashman workflow
Use the JSON formatter to inspect response shape, the Base64 tool for safe cursor wrappers, the timestamp converter to align sort keys with logs, and the diff tool to compare adjacent pages.
Keep the final note concrete: request parameters, returned cursor, first and last item keys, and whether the fix belongs in ordering, cursor encoding, or client retry handling.