hasura/graphql-engine · error · GraphqlConfigError

the fieldName for offsetInput needs to be defined in Graphql

Error message

the fieldName for offsetInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API

What it means

Raised when a model exposes a `selectMany` GraphQL API but the GraphqlConfig does not define the `offsetInput` fieldName. Offset pagination for list queries requires this argument name to be declared. Thrown during the graphql_config metadata resolution stage.

Source

Thrown at v3/crates/metadata-resolve/src/stages/graphql_config/error.rs:15

use graphql_types as ast;

use crate::types::error::ContextualError;

#[derive(Debug, thiserror::Error)]
pub enum GraphqlConfigError {
    #[error("graphql configuration is not defined in supergraph")]
    MissingGraphqlConfig,
    #[error("graphql configuration should be defined only once in supergraph")]
    MultipleGraphqlConfigDefinition,
    #[error(
        "the fieldName for limitInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API"
    )]
    MissingLimitFieldInGraphqlConfig,
    #[error(
        "the fieldName for offsetInput needs to be defined in GraphqlConfig, when models have a selectMany graphql API"
    )]
    MissingOffsetFieldInGraphqlConfig,
    #[error(
        "the filterInput needs to be defined in GraphqlConfig, when models have filterExpressionType"
    )]
    MissingFilterInputFieldInGraphqlConfig,
    #[error(
        "the orderByInput needs to be defined in GraphqlConfig, when models have orderByExpressionType"
    )]
    MissingOrderByInputFieldInGraphqlConfig,
    #[error(
        "the orderByInput.enumTypeNames needs to be defined in GraphqlConfig, when models have orderByExpressionType"
    )]
    MissingOrderByEnumTypeNamesInGraphqlConfig,
    #[error(
        "only one enumTypeNames can be defined in GraphqlConfig, whose direction values are both 'asc' and 'desc'."
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add `offsetInput: {fieldName: "offset"}` to the GraphqlConfig
2. Pair it with limitInput — selectMany requires both, so add limitInput too if also missing
3. Regenerate metadata with current tooling

Example fix

// before
{"graphql": {"limitInput": {"fieldName": "limit"}}}
// after
{"graphql": {"limitInput": {"fieldName": "limit"}, "offsetInput": {"fieldName": "offset"}}}

let needs_offset = models.iter().any(|m| m.has_select_many());
if needs_offset {
    assert!(config.offset_input.as_ref().is_some_and(|o| o.field_name.is_some()));
}

fn offset_ok(config: &GraphqlConfig, needs: bool) -> bool {
    !needs || config.offset_input.as_ref().is_some_and(|o| o.field_name.is_some())
}

Err(GraphqlConfigError::MissingOffsetFieldInGraphqlConfig) => { /* add offsetInput.fieldName and re-resolve */ }

When it happens

Trigger: Metadata contains a model with a selectMany GraphQL API and the GraphqlConfig has no `offsetInput` entry (or no fieldName within it); resolution/validation then fails.

Common situations: Same-family authoring mistakes as the limitInput variant: enabling selectMany without completing pagination config, migrating older metadata, or hand-writing config and forgetting the offset half.

Related errors

• the fieldName for limitInput needs to be defined in GraphqlC
• {value} is not a valid offset value
• {value} is not a valid limit value
• Field mapping not found for the field {field_name:} of type
• Object type '{type_name}' not found

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