hasura/graphql-engine · error · OrderByExpressionError

The order by expression {order_by_expression_name} reference

Error message

The order by expression {order_by_expression_name} referenced in orderable relationship {relationship_name} has not been defined

What it means

Same as 1076 but for orderable relationships: an orderable relationship entry references an order-by expression name that is not defined anywhere in the metadata.

Source

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

    #[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(
        "The type of the order by expression {order_by_expression_name} referenced in field {field_name} does not match the field type. Order by expression type: {order_by_expression_type}; field type: {field_type}. "
    )]
    OrderableFieldTypeError {
        order_by_expression_name: OrderByExpressionName,
        order_by_expression_type: TypeName,
        field_type: QualifiedBaseType,
        field_name: FieldName,
    },
    #[error("{0}")]
    GraphqlConfigError(#[from] graphql_config::GraphqlConfigError),
    #[error("{message}")]

View on GitHub (pinned to 724551b9ae)

Solutions

Define the referenced order-by expression
Correct or remove the order_by_expression_name on the orderable relationship

Defensive patterns

Strategy: validation

Validate before calling

const defined = new Set(Object.keys(orderByExpressions));
for (const r of orderableRelationships) if (r.order_by_expression_name && !defined.has(r.order_by_expression_name)) throw new Error(`Undefined order-by expression ${r.order_by_expression_name}`);

Prevention

Same as fields: validate relationship ordering references against defined expressions before apply

When it happens

Trigger: Configuring an orderable relationship with order_by_expression_name set to an undefined expression name.

Common situations: Renaming/deleting order-by expressions without updating relationship ordering config; typos in relationship ordering metadata.

Related errors

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