hasura/graphql-engine · error · OrderByExpressionIssue

Cannot order by array relationship {relationship_name} in or

Error message

Cannot order by array relationship {relationship_name} in order by expression {order_by_expression}

What it means

Thrown when an order-by expression tries to order by an array (many) relationship. Sorting by a one-to-many relationship is ambiguous (which element of the array determines the order?), so only object (single) relationships may be used in order-by expressions.

Source

Thrown at v3/crates/metadata-resolve/src/stages/order_by_expressions/types.rs:111

pub struct OrderableRelationship {
    /// order_by_expression is optional.
    /// If not present we will use order_by_expression from the model
    /// that the relationship targets.
    pub order_by_expression: Option<Qualified<OrderByExpressionName>>,
}

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct OrderByExpressionGraphqlConfig {
    pub expression_type_name: ast::TypeName,
}

#[derive(Debug, thiserror::Error)]
pub enum OrderByExpressionIssue {
    #[error("Duplicate order by expression found: {order_by_expression}")]
    DuplicateOrderByExpression {
        order_by_expression: Qualified<OrderByExpressionIdentifier>,
    },
    #[error(
        "Cannot order by array relationship {relationship_name} in order by expression {order_by_expression}"
    )]
    CannotOrderByAnArrayRelationship {
        order_by_expression: Qualified<OrderByExpressionIdentifier>,
        relationship_name: RelationshipName,
    },
    #[error(
        "The orderable field \"{field_name}\" has field arguments and cannot be used in order by expressions."
    )]
    OrderByFieldWithFieldArguments { field_name: FieldName },
}

impl ShouldBeAnError for OrderByExpressionIssue {
    fn should_be_an_error(&self, flags: &open_dds::flags::OpenDdFlags) -> bool {
        match self {
            OrderByExpressionIssue::DuplicateOrderByExpression { .. } => flags
                .contains(open_dds::flags::Flag::DisallowDuplicateNamesAcrossTypesAndExpressions),
            OrderByExpressionIssue::CannotOrderByAnArrayRelationship { .. } => {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the relationship named in the error: if it is genuinely one-to-many, it cannot be used for ordering — remove it from the expression
2. If the relationship should be single-object, fix its kind/type in the relationship definition
3. Order by a field of the related type via an object relationship instead

Example fix

# before
order_by:
  - relationship: comments   # array relationship
    field: createdAt
# after
order_by:
  - relationship: author     # object relationship
    field: name

const rel = relationships[expr.relationship_name];
if (rel?.kind === 'ArrayRelationship') {
  throw new Error('cannot order by array relationship');
}

const isObjectRelationship = (r) => r?.kind === 'ObjectRelationship';

When it happens

Trigger: Referencing an array/many relationship inside an order_by_expressions entry during resolution; the relationship's cardinality is Array, which the resolver rejects with CannotOrderByAnArrayRelationship.

Common situations: Trying to order posts by their comments, or a type by any of its one-to-many relations, in metadata; mis-declaring a relationship's kind as Array when it should be Object.

Related errors

• {message}
• The orderable relationship '{relationship_name}' defined for
• Duplicate order by expression found: {order_by_expression}
• The orderable field "{field_name}" has field arguments and c
• The orderable relationship '{relationship_name}' defined for

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