hasura/graphql-engine · error · NamedOrderByExpressionError

Error in order by expression {order_by_expression_name}: {er

Error message

Error in order by expression {order_by_expression_name}: {error}

What it means

Wrapper error attaching the name of the order-by expression to an underlying OrderByExpressionError. The message shows which named order_by_expression failed and the inner error describing the specific problem in its definition.

Source

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

use crate::stages::graphql_config;
use crate::types::error::ContextualError;
use crate::types::subgraph::{Qualified, QualifiedBaseType};

use open_dds::{
    order_by_expression::OrderByExpressionName,
    relationships::RelationshipName,
    types::{CustomTypeName, FieldName, TypeName},
};

#[derive(Debug, thiserror::Error)]
#[error("Error in order by expression {order_by_expression_name}: {error}")]
pub struct NamedOrderByExpressionError {
    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>,

View on GitHub (pinned to 724551b9ae)

Solutions

Look at the inner error text after the colon to identify the concrete failure in the named expression
Fix the expression definition (field names, relationships, types) in metadata
If referenced entities were renamed, update the expression or delete it and recreate it

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate every named expression resolves against the current schema before apply
for (const [name, expr] of Object.entries(orderByExpressions)) {
  if (!expressionResolves(expr, objectTypes, relationships)) throw new Error(`Invalid order-by expression ${name}`);
}

Try / catch

// Catch and unwrap the named wrapper to log which expression failed
try { await applyMetadata(md); }
catch (e) { if (String(e).startsWith('Error in order by expression')) console.error(e); throw e; }

Prevention

Lint order-by expressions whenever fields or relationships change
Delete unused expressions during cleanup

When it happens

Trigger: Resolving a named order-by expression (e.g. one referenced by an orderable field) whose body is invalid — unknown field, unknown relationship, undefined type, or graphql config problems bubble up here.

Common situations: An order_by_expression defined in metadata references fields or relationships that do not exist or were renamed; the expression's type disagrees with field types.

Related errors

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