hasura/graphql-engine · error · OrderByExpressionError

unknown field {field_name} in orderable fields

Error message

unknown field {field_name} in orderable fields

What it means

An order-by expression references a field name that is not among the orderable fields of the type under construction. The resolver only allows ordering by fields explicitly marked orderable, so unknown field names are rejected.

Source

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

    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>,
    },
    #[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"

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the field name spelling in the order-by expression against the type's fields
2. Ensure the field exists on the object type and is eligible for ordering
3. Update or remove stale order-by expressions after field renames

Example fix

// before
{"expression":{"field":"full_name"}}
// after
{"expression":{"field":"name"}}

// Check expression fields exist on the type
const fields = new Set(objectType.fields.map(f => f.name));
for (const name of referencedFields(expression)) if (!fields.has(name)) throw new Error(`Unknown field ${name} in order-by expression`);

When it happens

Trigger: Writing an order_by_expression like {field: "name"} where 'name' is not a field of the type, is misspelled, or is a field not marked as orderable.

Common situations: Renaming a field without updating order-by expressions; typos in expression definitions; referencing a field that exists on the database but not in the mapped object type.

Related errors

• Error in order by expression {order_by_expression_name}: {er
• The data type {data_type} has not been defined
• The relationship {relationship_name} on object type {object_
• Invalid orderable field {field_name}. Exactly one of `enable
• The order by expression {order_by_expression_name} reference

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