hasura/graphql-engine · error · Error

{value} is not a valid offset value

Error message

{value} is not a valid offset value

What it means

The offset counterpart to the limit error: pagination offset arguments must fall within the accepted range. When the offset value provided in a query fails IR validation, this error reports the exact value. It guards data sources against invalid skip values (out-of-range or rejected by the argument parser).

Source

Thrown at v3/crates/graphql/ir/src/error.rs:61

        decoding_error: String,
    },

    #[error("Unexpected value: expecting {expected_kind:}, but found: {found:}")]
    UnexpectedValue {
        expected_kind: &'static str,
        found: json::Value,
    },

    #[error("'{name:}' is not a valid GraphQL name.")]
    TypeFieldInvalidGraphQlName { name: String },

    #[error("'{alias:} is not a valid alias")]
    InvalidAlias { alias: String },

    #[error("{value} is not a valid limit value")]
    InvalidLimitValue { value: u32 },

    #[error("{value} is not a valid offset value")]
    InvalidOffsetValue { value: u32 },

    #[error("field '{field_name:} not found in entity representation")]
    FieldNotFoundInEntityRepresentation { field_name: FieldName },

    #[error(
        "order_by expects a list of input objects with exactly one key-value pair per input object. Please split the input object with multiple key-value pairs into a list of single key-value pair objects."
    )]
    OrderByObjectShouldExactlyHaveOneKeyValuePair,

    #[error("missing non-nullable argument {argument_name:} for field {field_name:}")]
    MissingNonNullableArgument {
        argument_name: String,
        field_name: String,
    },

    #[error("Only one subscription root field is allowed")]
    NoneOrMoreSubscriptionRootFields,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Clamp or reduce the offset to within the allowed range before sending
2. Prefer cursor-based pagination for deep paging instead of large numeric offsets
3. If you operate the server, review/raise the configured max offset and document it in the schema

Example fix

# before
query {{ items(offset: 5000000, limit: 100) {{ id }} }}

# after
query {{ items(first: 100, after: "<cursor>") {{ edges {{ cursor node {{ id }} }} }} }}

const MAX_OFFSET = 10000;
const offset = Math.max(0, Math.min(requestedOffset, MAX_OFFSET));

function isValidOffset(v: number, max = 10000): v is number {{
  return Number.isInteger(v) && v >= 0 && v <= max;
}}

try {{
  await fetchItems({{ offset }});
}} catch (e: any) {{
  if (/not a valid offset value/.test(e.message)) {{
    return fetchItems({{ offset: 0 }}); // restart from beginning
  }}
  throw e;
}}

When it happens

Trigger: Passing an offset argument outside the accepted range for a connection/field — e.g. an offset exceeding the maximum allowed offset, or a value rejected during IR construction from request arguments.

Common situations: Deep-pagination requests with huge computed offsets (page * pageSize overflow); clients sending negative or oversized offsets after config tightening; cursor-vs-offset migration mistakes sending cursor values as offsets.

Related errors

• {value} is not a valid limit value
• validation failed: {0}
• Unexpected value: expecting {expected_kind:}, but found: {fo
• '{name:}' is not a valid GraphQL name.
• '{alias:} is not a valid alias

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/669e8364ea569608. Report an issue: GitHub.