Server‑Side LIST pagination: when does a continue token expire?

Question

Server‑Side LIST pagination: when does a continue token expire?
When exporting a large set of objects with the API server’s LIST chunking, clients supply limit and receive a continue token in metadata.continue. The next call repeats the query with that token. In practice, the token is tied to a snapshot resourceVersion, and if the snapshot becomes stale or the underlying data changes, the server may return 410 Gone or ResourceExpired. This behavior is documented but not fully exposed in client examples, leaving teams uncertain about how long a token remains valid or what triggers expiration.
Key uncertainties include:

What specific conditions cause the API server to reject a continue token?
Is there a documented timeout or resourceVersion mismatch that triggers a 410 Gone?
When a token is invalid, should a client restart the LIST from the beginning or attempt a fallback strategy?

Tasadduq Burney · Answer

Answer: The continue token expires when its encoded resourceVersion is older than the etcd compacted revision (or when the API server loses the watch cache entry). There is no fixed time‑out; validity depends on how quickly etcd compacts old revisions.
Confirmed facts

The token contains the resourceVersion of a consistent snapshot taken at the start of the LIST.
If that resourceVersion is less than the current etcd compacted revision, the API server returns HTTP 410 Gone with a ResourceExpired status.
Expiration can also occur after an API server restart that discards the watch cache, or when underlying object changes make the snapshot不可保证.
The timing is governed by etcd compaction flags: --auto-compaction-retention (default 5 min) and --auto-compaction-interval (default 5 min). No separate token timeout exists.
On receiving 410 Gone, the client should restart the LIST from the beginning (or from a fresh LIST without continue) rather than retrying the same token.

Steps to verify or act on expiration

Obtain a continue token and note the returned metadata.resourceVersion.
Check the current etcd compacted revision (e.g., etcdctl endpoint status --write-out=json or etcdctl get /registry/minrev depending on your cluster).
If the token’s resourceVersion is less than the compacted revision, the next LIST with that token will yield 410 Gone.
Upon 410 Gone, discard the token and issue a new LIST request with the same limit and no continue parameter to start a fresh snapshot.

If you are unsure about the etcd compaction retention setting on your cluster, please provide that value; it determines how long a token may remain valid and could affect the recommendation.

Server‑Side LIST pagination: when does a continue token expire?

Server‑Side LIST pagination: when does a continue token expire?

1 answer

Answer: The continue token expires when its encoded resourceVersion is older than the etcd compacted revision (or when the API server loses the watch cache entry). There is no fixed time‑out; validity depends on how quickly etcd compacts old revisions.

Confirmed facts

Steps to verify or act on expiration

Your perspective belongs here.

0 question comments