Your list call returns the first page and a nextCursor, and every caller writes the same loop
around it. One caller forgets to stop when the loop body is done, and fetches the remaining pages
for nothing. Another reads a 500 on page two as the end of the list, and ships a report with a
third of the books in it.
What you get
You will end up with a client method that returns an iter.Seq2[Book, error], and tests for the
three ways a range loop over it ends. This is for you if you write a Go client for a paged API and
want callers to range over every item.
Short answer
Return an iter.Seq2[Book, error] whose function fetches one page, yields each book, and follows
the next cursor until there is none. Return as soon as yield returns false, so a break stops the
fetching. Check ctx before each request and build the request with it. Yield a failed page or a
cancelled context as one last pair with a zero Book. Say in the doc comment that the books before
that pair are only part of the list.
You will need
Go 1.23 or later, which runs a range over a function, and an
API whose list endpoint returns a next cursor. Verified 2026-11-22 against Go 1.24.7, @voxgig/sdkgen
4.44.3 and Swagger Codegen 3.0.85. The prerequisite page,
loop over every page of a REST collection, covers the
loop itself.
The document, api.json, has one list operation: GET /books with limit and cursor, answering
{ items, nextCursor }, where nextCursor is null on the last page. The stand-in in standin/
holds requests to it: a limit outside 1 to 100 or a cursor it never issued is a 400.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| AWS SDK for Go v2 paginators | You call AWS, whose SDK ships a paginator for each paginated operation | An explicit HasMorePages and NextPage loop at every call site, page by page | You want callers to range over items |
| Fern Go auto-pagination | Fern generates your Go SDK from a document with x-fern-pagination | A Next, Current and Err iterator, and a free plan that covers Python and TypeScript only | You need a range loop without an adapter |
go-github ListOptions and Iter methods | You call GitHub from Go | A page-number loop on resp.NextPage, or generated Iter methods for GitHub only | Your API is not GitHub |
iter.Seq2 with a yield loop | You write the client, and callers range over items | A function per list operation, and the three stops to write and test yourself | A generator already writes paging for your API |
| sdkgen paging feature | You generate several languages and want one paging signal in each | A control map you pass on every call, no context.Context, and a channel stream | Callers need cancellation mid-walk |
| Swagger Codegen go client | You want a generated Go client from the document with no account | One page per call, no paging code, and a null cursor typed as string | You want the generator to page for you |
Voxgig maintains sdkgen. The table lists it beside five other ways to page in Go, alphabetically, with no ranking.
The iter.Seq2 route costs a function per list operation and gives callers the loop the language
offers. The AWS paginator and Fern’s iterator are both explicit loops, so each caller writes the
three stops. go-github’s generated Iter methods already have the shape this page builds. Swagger
Codegen’s go client leaves paging to you, and sdkgen pages through a control map at the price of
cancellation.
Yield one book at a time, and the error last
Books fetches a page only after the caller has consumed the one before it, so it never has a
request in flight that nobody asked for. The doc comment says what a caller must not do with a
truncated list.
// Books yields every book on every page, fetching a page only when the
// caller has consumed the one before it.
//
// The sequence ends in one of three ways. It ends after the last book when
// the server sends no next cursor. It ends early, with no further request,
// when the loop body breaks or returns. It ends with a final pair whose error
// is non-nil when a request fails, the context is done, or the server sends a
// cursor it already sent; the books yielded before that pair are only part of
// the list, so a caller that ignores the error must not treat them as
// complete. The error is a *PageError naming the page and its cursor.
func (c *Client) Books(ctx context.Context) iter.Seq2[Book, error] {
return func(yield func(Book, error) bool) {
cursor := ""
seen := map[string]bool{}
for page := 1; ; page++ {
if err := ctx.Err(); err != nil {
yield(Book{}, &PageError{Page: page, Cursor: cursor, Err: err})
return
}
p, err := c.FetchPage(ctx, cursor)
if err != nil {
pe, ok := err.(*PageError)
if !ok {
pe = &PageError{Err: err}
}
pe.Page, pe.Cursor = page, cursor
yield(Book{}, pe)
return
}
for _, b := range p.Items {
if !yield(b, nil) {
return
}
}
if p.NextCursor == nil || *p.NextCursor == "" {
return
}
if seen[*p.NextCursor] {
yield(Book{}, &PageError{Page: page + 1, Cursor: *p.NextCursor, Err: fmt.Errorf("the server sent a cursor it already sent")})
return
}
seen[*p.NextCursor] = true
cursor = *p.NextCursor
}
}
}
The error belongs in the pair because a range loop has nowhere else to put it. A separate Err()
method, read after the loop, is a step a caller can skip without a compiler noticing, while the
second variable of the pair is right there in the for clause. Calling yield again after it has
returned false is a runtime panic, so every return after a refused yield is there to prevent one.1
Stop on break, on cancel, and on a failed page
cmd/demo runs each ending against a fresh stand-in, three books to a page, and counts the list
requests the client sent.
go run ./cmd/demo
every book b1 b2 b3 b4 b5 b6 b7 b8 b9 requests: 3
break after four b1 b2 b3 b4 requests: 2
cancel at b4 b1 b2 b3 b4 b5 b6 requests: 2 last pair: page 3 (cursor "c6"): context canceled
page 2 fails b1 b2 b3 requests: 2 last pair: page 2 (cursor "c3"): HTTP 500
page 2 fails, err as _ 4 books, 1 of them with no id, and no error reached the caller
A break after the fourth book means page three is never requested. A cancel at b4 lets the books
already fetched through, then ends with context canceled before the third request. A 500 on page
two ends with a PageError that names the page and the cursor it was sent with.
The last line is the pitfall. A caller who writes for b, _ := range gets three real books and the
zero Book that carried the error, and the loop ends the way a complete one does.
Page with Swagger Codegen and sdkgen
Swagger Codegen’s go client has one ListBooks call per page and no paging code. Its BookPage
types the cursor as a plain string, so null and "" both arrive as "":
type BookPage struct {
Items []Book `json:"items"`
NextCursor string `json:"nextCursor"`
}
adapters.SwaggerBooks puts the same iter.Seq2 over it, and ends on "". The sdkgen Go target,
scaffolded with --feature paging, records the next cursor in a control map passed to every
List call. adapters.SdkgenBooks wraps that, and checks ctx only between pages, because the
SDK’s calls take no context.Context.
go run ./cmd/compare
Swagger Codegen ListBooks, called once 3 books, NextCursor "c3", err <nil>
Swagger Codegen with adapters.SwaggerBooks 9 books, requests: limit=3 | cursor=c3&limit=3 | cursor=c6&limit=3
sdkgen paging, body field "nextCursor" 9 books, requests: limit=3&page=1 | cursor=c3&limit=3 | cursor=c6&limit=3
sdkgen paging, body field "next" 3 books, requests: limit=3&page=1
last pair: page 2: hasMore is true and no cursor was recorded (paging map[hasMore:true next:c3])
sdkgen Stream("list") 3 items from 1 request
sdkgen Stream, 5 left after one item 5 goroutines still parked; with a closed signal, 0
Fern's Next, Current, Err shape, wrapped b1 b2 b3, then: HTTP 500 on page 2
The page’s document names the field nextCursor because that is a name the paging feature sends
back. With the same stand-in answering next, the feature records next and sends nothing on, so
the adapter stops with an error where the documented loop would ask for page one again.2 The
first request also carries page=1, which api.json does not declare. @voxgig/sdkgen 4.45.0
writes the same Go files, byte for byte.
Stream("list") returns a channel of one call’s items. A caller who stops reading leaves the
goroutine behind it parked on a send, five of them for five abandoned streams, unless a signal
channel was passed in callopts and closed. The generated REFERENCE.md describes the channel and
its last Err item but not signal, which the Go README leaves out too. A break out of an
iter.Seq2 needs no such cleanup.
Page with Fern’s Go SDK
Fern reads the paging from the document, through an
x-fern-pagination
extension on the operation: cursor: $request.cursor, next_cursor: $response.nextCursor and
results: $response.items for this one. Its auto-pagination page says the Go SDK then returns a
*core.Page[T], whose Iterator() has Next(ctx), Current() and Err(), and whose
GetNextPage(ctx) goes page by page. The page shows no range-over-func form.
adapters.FromIterator turns that shape into an iter.Seq2, with Err as the last pair. It was
tested against a fake with the documented methods, the last line of the cmd/compare output, because no
Fern client was generated. Fern’s pricing page puts Python and
TypeScript SDKs on the free plan, and Go among the ten SDK languages of the Enterprise plan.
Stainless is left out: its announcement
of May 18, 2026 says new signups, projects, and SDKs are no longer available.
Check it worked
node check.mjs
pass adapters TestFromIterator
pass adapters TestSdkgenAdapterStops
pass adapters TestSdkgenAdapterStops/all
pass adapters TestSdkgenAdapterStops/break
pass adapters TestSdkgenAdapterStops/cancel
pass adapters TestSdkgenAdapterStops/cursor_field_named_next
pass adapters TestSdkgenAdapterStops/later_page_fails
pass adapters TestSdkgenFirstRequestCarriesPageOne
pass adapters TestSwaggerAdapterStops
pass adapters TestSwaggerAdapterStops/all
pass adapters TestSwaggerAdapterStops/break
pass adapters TestSwaggerAdapterStops/cancel
pass adapters TestSwaggerAdapterStops/later_page_fails
pass books TestAPageWithoutItemsIsAnError
pass books TestARepeatedCursorIsAnError
pass books TestBreakStopsFetching
pass books TestCancelEndsTheSequenceWithTheContextError
pass books TestErrorOnALaterPageIsTheLastPair
pass books TestEveryPageInOrder
pass books TestNoPageIsFetchedAhead
pass books TestTheStandInRefusesWhatTheDocumentRefuses
pass books TestYieldAfterFalsePanics
22 tests and subtests, 0 not passed
check.mjs runs go test -json and prints the results in a fixed order, so the summary is the same
on every run, and it exits 1 when a package fails to build. Each stop has a test for the
hand-written iterator and for both adapters, and each counts the requests the stand-in received.
TestNoPageIsFetchedAhead shows that Books never has a request in flight while the loop body
runs, so no failed fetch can land behind the caller.
When it goes wrong
A loop over the iterator panics. The message reads range function continued iteration after function for loop body returned false, and it means a yield was called after it returned false,
usually because a loop over a page’s items kept going. Return on the first false.
The walk never ends. The server sent a cursor it had sent before, and the client follows it in a
circle. Books keeps the cursors it has followed and ends with an error on a repeat.
A caller reports a short list as complete. The error half of the pair was dropped with _, and the
loop ended normally. Name the second variable, and reject , _ := range over a sequence that
carries errors in review.
When not to do this
Do not wrap a client whose SDK already ranges. go-github v93.0.0 generates
ListByOrgIter and
its siblings with this page’s yield loop and the error as the last pair. A wrapper only adds a
layer to keep in step. That release needs Go 1.26, as its go.mod says.
Do not hide a paging channel behind iter.Seq2 without closing the channel’s signal on every
exit, since the sdkgen Stream goroutines stay parked otherwise. Do not use the sdkgen paging
feature where a walk must be cancelled mid-request, because its calls take no context. Fern suits a
team that already generates its SDKs with Fern and can pay for a plan that includes Go, since its iterator comes
with every paged operation and needs one adapter. Swagger Codegen suits a team that wants a Go
client from the document with no account at all, and is content to write the loop.
Related how-tos
Last verified
Verified 2026-11-22 against Go 1.24.7, Node 22.23.5, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, and Swagger Codegen 3.0.85 on OpenJDK 21, with
golang.org/x/oauth2 v0.30.0 and github.com/antihax/optional v1.0.0 pinned for the Swagger
Codegen client. The generators ran once, in record.sh, and their output is committed. Fern was not
run, because generating needs a Fern login or Docker. Its Go SDK shape comes from the Current
version of its auto-pagination page, and its plans from its pricing page. The go-github method was
read at its v93.0.0 tag, from the Go module proxy, in record.sh. Every output block is what the
command preceding it printed.
Footnotes
-
The specification gives the rule in one sentence: if the loop body terminates, such as by a
break,yieldreturns false and must not be called again. It leaves the consequence to the runtime, which in Go 1.24.7 panics with a message naming the range function, asTestYieldAfterFalsePanicsrecords. The Go blog post on range functions, dated August 20, 2024, states what the iterator does, more mildly: whenyieldreturns false, no more values are needed. ↩︎ Back to text -
The features reference lists
next,cursorandnextCursoramong the body fields the feature understands, and says the next call continues from a recordedcursor, or else fromnextPage. A bodynextis recorded under its own name, which is neither of the two the next call reads. ↩︎ Back to text