hasura/graphql-engine · error · OrderByExpressionError

The relationship {relationship_name} on object type {object_

Error message

The relationship {relationship_name} on object type {object_type_name} could not be found

What it means

An order-by expression traverses a relationship that does not exist on the given object type. Order-by expressions can follow relationships (order by a related object's field), and the relationship name must resolve against the type's declared relationships.

Source

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

    pub order_by_expression_name: Qualified<OrderByExpressionName>,
    pub error: OrderByExpressionError,
}

impl ContextualError for NamedOrderByExpressionError {
    fn create_error_context(&self) -> Option<error_context::Context> {
        None
    }
}

#[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(

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the relationship name against the relationships declared on that object type
2. Define the missing relationship in metadata or fix the name in the expression
3. Update expressions after relationship renames

const rels = new Set(objectType.relationships?.map(r => r.name) ?? []);
for (const r of referencedRelationships(expression)) if (!rels.has(r)) throw new Error(`Unknown relationship ${r} in order-by expression`);

When it happens

Trigger: Expression contains a relationship segment naming a relationship not defined on the object type — misspelled, renamed, or defined on a different type.

Common situations: Renaming relationships without updating expressions; referencing a relationship that exists in the database but was not declared in metadata; expressions copied between types.

Related errors

• The order by expression {order_by_expression_name} reference
• the relationship '{relationship_name}' is defined more than
• the comparable relationship '{relationship_name}' for the op
• the comparable relationship '{relationship_name}' for the op
• relationship '{relationship_name}' is used in comparableRela

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