hasura/graphql-engine · error · OrderByExpressionError

Invalid orderable field {field_name}. Exactly one of `enable

Error message

Invalid orderable field {field_name}. Exactly one of `enable_order_by_directions` or `order_by_expression_name` must be specified.

What it means

A field is configured as an orderable field, but its configuration is ambiguous: exactly one of enable_order_by_directions or order_by_expression_name must be set, and the resolver found both or neither.

Source

Thrown at v3/crates/metadata-resolve/src/stages/order_by_expressions/error.rs:39

    }
}

#[derive(Debug, thiserror::Error)]
pub enum OrderByExpressionError {
    #[error("unknown field {field_name} in orderable fields")]
    UnknownFieldInOrderByExpression { field_name: FieldName },
    #[error("The data type {data_type} has not been defined")]
    UnknownOrderableType {
        data_type: Qualified<CustomTypeName>,
    },
    #[error(
        "The relationship {relationship_name} on object type {object_type_name} could not be found"
    )]
    UnknownRelationship {
        relationship_name: RelationshipName,
        object_type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "Invalid orderable field {field_name}. Exactly one of `enable_order_by_directions` or `order_by_expression_name` must be specified."
    )]
    InvalidOrderByExpressionOrderableField { field_name: FieldName },
    #[error(
        "The order by expression {order_by_expression_name} referenced in field {field_name} has not been defined"
    )]
    UnknownOrderByExpressionNameInOrderableField {
        order_by_expression_name: OrderByExpressionName,
        field_name: FieldName,
    },
    #[error(
        "The order by expression {order_by_expression_name} referenced in orderable relationship {relationship_name} has not been defined"
    )]
    UnknownOrderByExpressionNameInOrderableRelationship {
        order_by_expression_name: OrderByExpressionName,
        relationship_name: RelationshipName,
    },
    #[error(

View on GitHub (pinned to 724551b9ae)

Solutions

1. Edit the orderable field entry so exactly one of the two options is present
2. Use enable_order_by_directions for plain direction-based ordering, or order_by_expression_name to delegate ordering to a named expression

Example fix

// before
{"field":"name","enable_order_by_directions":true,"order_by_expression_name":"name_expr"}
// after
{"field":"name","enable_order_by_directions":true}

for (const f of orderableFields) {
  const a = f.enable_order_by_directions != null, b = f.order_by_expression_name != null;
  if (a === b) throw new Error(`Orderable field ${f.field} must set exactly one of the two options`);
}

When it happens

Trigger: Orderable field entry sets both enable_order_by_directions and order_by_expression_name, or sets neither, leaving the resolver unable to decide how ordering works for that field.

Common situations: Hand-editing orderable_fields entries; migrating metadata between format versions where defaults changed; copy-paste combining two configuration styles.

Related errors

• {0}
• Error in order by expression {order_by_expression_name}: {er
• unknown field {field_name} in orderable fields
• The data type {data_type} has not been defined
• The relationship {relationship_name} on object type {object_

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