hasura/graphql-engine · error · GraphqlConfigError

the orderByInput needs to be defined in GraphqlConfig, when

Error message

the orderByInput needs to be defined in GraphqlConfig, when models have orderByExpressionType

What it means

Raised when a model declares an `orderByExpressionType` but the GraphqlConfig does not define `orderByInput`. Order-by support requires a named orderBy input argument in the GraphQL schema, which must be configured. Thrown during the graphql_config resolution stage.

Source

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

#[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'."
    )]
    MultipleOrderByEnumTypeNamesInGraphqlConfig,
    #[error(
        "invalid directions: {directions} defined in orderByInput of GraphqlConfig , currently there is no support for partial directions. Please specify a type which has both 'asc' and 'desc' directions"
    )]
    InvalidOrderByDirection { directions: String },
    #[error(
        "the fieldName for argumentsInput needs to be defined in GraphqlConfig, when models have argumentsInputType"
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add `orderByInput: {fieldName: "order_by"}` to GraphqlConfig
2. Also define its enumTypeNames since orderBy support requires the direction enum (see the companion error)
3. Regenerate metadata with current templates

Example fix

// before
{"graphql": {}, "models": [{"orderByExpressionType": "users_order_by"}]}
// after
{"graphql": {"orderByInput": {"fieldName": "order_by", "enumTypeNames": [{"name": "OrderByDirection", "directions": {"asc": "asc", "desc": "desc"}}]}}, "models": [{"orderByExpressionType": "users_order_by"}]}

let uses_order = models.iter().any(|m| m.order_by_expression_type.is_some());
if uses_order {
    assert!(config.order_by_input.as_ref().is_some_and(|o| o.field_name.is_some()));
}

fn order_by_ok(config: &GraphqlConfig, models: &[Model]) -> bool {
    !models.iter().any(|m| m.order_by_expression_type.is_some())
        || config.order_by_input.as_ref().is_some_and(|o| o.field_name.is_some())
}

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

When it happens

Trigger: Metadata contains a model with orderByExpressionType while GraphqlConfig lacks the `orderByInput` entry; resolution of this metadata fails.

Common situations: Adding sorting capabilities to models without updating the shared graphql config; migrations from older metadata versions where orderByInput was optional; partial configs written by hand.

Related errors

• the orderByInput.enumTypeNames needs to be defined in Graphq
• invalid directions: {directions} defined in orderByInput of
• graphql configuration is not defined in supergraph
• the filterInput needs to be defined in GraphqlConfig, when m
• only one enumTypeNames can be defined in GraphqlConfig, whos

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