OUT_OF_RANGE
GCP OUT_OF_RANGE means the request is structurally valid, but a requested value, offset, cursor, or range falls outside the currently valid bounds.
Last reviewed: April 24, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Out Of Range Mean?
The input shape is valid, but one value only makes sense inside a bounded range and the request crossed that boundary. Recovery depends on whether this is a normal terminal iterator signal, stale bounds after data changed, or a caller bug that should be clamped before dispatch.
Common Causes
- -Offset, index, page token, byte range, or cursor exceeds current dataset or resource bounds.
- -The request uses a state-dependent value that became invalid after compaction, deletion, append, or reindexing.
- -Client assumes static limits while the backend enforces dynamic live limits.
- -Iterator logic treats a terminal boundary as an error and keeps retrying the same out-of-range request.
- -Cached size, page count, or cursor metadata is reused after the underlying resource changed.
How to Fix Out Of Range
- 1Read current resource bounds before building range, page, or cursor-based requests.
- 2Guard pagination and cursor loops so expected end-of-range responses terminate cleanly.
- 3Recompute offsets, limits, and page tokens after mutation, compaction, or reindex events.
- 4Clamp caller-controlled numeric values before dispatch and route always-invalid inputs to INVALID_ARGUMENT diagnostics.
- 5Reset from a stable checkpoint when a saved cursor is no longer valid for the current dataset.
Step-by-Step Diagnosis for Out Of Range
- 1Capture failed offsets, limits, indexes, cursors, page tokens, and current resource size metadata.
- 2Compare caller assumptions with live service-reported bounds before retrying.
- 3Determine whether OUT_OF_RANGE is expected terminal behavior or unexpected mid-scan failure.
- 4Validate cursor invalidation and checkpoint restart behavior after data mutation events.
- 5Retest with recomputed bounds and confirm pagination or range loops terminate without duplicate or skipped work.
Seen in Production
- -A chunk reader caches object size, the object is compacted, and the next byte-range read lands beyond the current end.
- -A batch scanner stores a page token overnight, backend reindexing invalidates it, and every resumed job fails with OUT_OF_RANGE.
- -A UI page selector assumes a fixed page count while concurrent deletes shrink the result set.
- -An iterator reaches a documented terminal boundary, but worker logic treats it as retryable failure and loops forever.
Live Bound and Cursor Validation
- -Query current bounds before each range request (example: object size changed between chunk reads, making old offset invalid).
- -Invalidate stale cursors after writes or compaction events (example: saved page token no longer valid after dataset mutation).
Iterator Termination Logic
- -Treat out-of-range as terminal where API semantics indicate end-of-sequence.
- -Differentiate from invalid-argument errors that are always bad regardless of state (example: negative offset should be fixed in client validation).
Decision Shortcut: Terminal Boundary vs Bug
- -If the API documents OUT_OF_RANGE as end-of-sequence, stop iteration and mark the scan complete.
- -If the same cursor was valid before data changed, reset from a stable checkpoint or refresh live bounds.
- -If the value is impossible in all states, such as a negative offset, move to INVALID_ARGUMENT instead.
Wrong Fix to Avoid
- -Do not blindly retry the same out-of-range cursor or offset.
- -Do not treat terminal iterator completion as an outage.
- -Do not reuse cached size or page-count metadata after mutation-heavy workflows.
Implementation Examples
{
"requestId": "req_range_211",
"status": "OUT_OF_RANGE",
"cursor": "page_944",
"cachedResultCount": 12000,
"currentResultCount": 8400
}gcloud logging read 'textPayload:OUT_OF_RANGE OR jsonPayload.status="OUT_OF_RANGE"' --limit=20{
"outOfRangeMode": "terminal_end_of_sequence",
"action": "stop_iteration",
"checkpoint": "completed"
}Incident Timeline
08:12 UTC
A caller builds a request from stale bounds or cursor state
Signal: Cached size, page token, offset, or index metadata no longer matches the current resource.
Why it matters: The first useful question is whether the requested bound is still valid right now.
08:13 UTC
The service rejects the request with OUT_OF_RANGE
Signal: The input is structurally valid, but the requested range crosses the current limit.
Why it matters: This is not necessarily malformed input; it may be stale or terminal state.
08:15 UTC
Workers retry the same invalid boundary
Signal: Pagination or chunk readers replay the same cursor, offset, or range and fail repeatedly.
Why it matters: Progress returns only after bounds are recomputed or the terminal condition is handled.
08:22 UTC
Bounds are refreshed and iteration resumes or terminates cleanly
Signal: The job reloads resource metadata, resets from a checkpoint, or stops at the documented end of sequence.
Why it matters: That confirms the problem lived in stale range state or iterator control flow.
Seen in Production
Chunk reader uses stale file size after append/compact operation
Frequency: common
Example: Reader requests byte range beyond current valid end offset and receives OUT_OF_RANGE.
Fix: Re-fetch object metadata before each chunk and recompute next range.
Batch scanner retries expired page token indefinitely
Frequency: medium
Example: Token becomes invalid after backend reindex and job loops with repeated out-of-range responses.
Fix: Reset scan from stable checkpoint when token validation fails.
UI page count becomes stale after concurrent deletes
Frequency: common
Example: User requests page 18 from a result set that now only has 12 pages.
Fix: Refresh result count and move the user to the nearest valid page or restart pagination.
Wrong Fix vs Better Fix
Retry same cursor vs refresh live bounds
Wrong fix: Replay the same page token, offset, or byte range after OUT_OF_RANGE.
Better fix: Fetch live bounds or reset from a stable checkpoint before issuing the next request.
Why this is better: The old boundary may no longer be valid after mutation, compaction, or reindexing.
Treat completion as failure vs terminate cleanly
Wrong fix: Keep retrying when OUT_OF_RANGE is the documented end-of-sequence signal.
Better fix: Mark the iterator complete and persist a final checkpoint.
Why this is better: Some OUT_OF_RANGE responses mean there is no more valid work to request.
Clamp everything silently vs classify bad input
Wrong fix: Clamp every out-of-range value without understanding whether it is terminal, stale, or invalid.
Better fix: Separate terminal bounds, stale cursor state, and always-invalid caller inputs into distinct handling paths.
Why this is better: Silent clamping can hide skipped work or broken pagination contracts.
Debugging Tools
- -Service-specific list/get APIs for live bound metadata
- -Cursor and pagination trace logs
- -Boundary-focused integration tests
- -Job-level iterator progress metrics
How to Verify the Fix
- -Replay range or pagination calls and confirm OUT_OF_RANGE is only seen at expected terminal boundaries.
- -Validate iterator loops now terminate gracefully without redundant retries.
- -Check data-processing jobs complete full scans without skipping or duplicating segments.
- -Confirm stale cursor and mutated-dataset tests restart from a stable checkpoint.
How to Prevent Recurrence
- -Compute range boundaries from live metadata instead of cached or hardcoded limits.
- -Implement cursor invalidation and restart rules after write-heavy operations.
- -Add contract tests for boundary transitions and end-of-sequence behavior.
- -Emit separate telemetry for terminal OUT_OF_RANGE, stale cursor recovery, and unexpected bounds bugs.
Pro Tip
- -store cursor generation or dataset version with checkpoints so stale resumes can be rejected before dispatch.
Official References
Provider Context
This guidance is specific to GCP services. Always validate implementation details against official provider documentation before deploying to production.