hasura/graphql-engine · error · TypePredicateError

field '{field_name}' of type '{type_name}' used in a field c

Error message

field '{field_name}' of type '{type_name}' used in a field comparison is a predicate type and therefore cannot be compared to a single value

What it means

A field comparison to a single value was attempted on a field whose type is itself a predicate/boolean-expression type. Predicate types are structured filter inputs, not comparable scalars, so comparing them to a single value is meaningless and rejected.

Source

Thrown at v3/crates/metadata-resolve/src/types/error.rs:457

    #[error(
        "field '{field_name}' of type '{type_name}' used in a field comparison has the unknown NDC type '{ndc_type_name}' and therefore cannot be compared to a single value"
    )]
    UnsupportedFieldComparisonToUnknownType {
        field_name: Spanned<FieldName>,
        field_type: QualifiedTypeReference,
        type_name: Qualified<CustomTypeName>,
        ndc_type_name: ndc_models::TypeName,
    },

    #[error(
        "field '{field_name}' of type '{type_name}' used in a field comparison is an array type and therefore cannot be compared to a single value"
    )]
    UnsupportedFieldComparisonToArrayType {
        field_name: Spanned<FieldName>,
        field_type: QualifiedTypeReference,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "field '{field_name}' of type '{type_name}' used in a field comparison is a predicate type and therefore cannot be compared to a single value"
    )]
    UnsupportedFieldComparisonToPredicateType {
        field_name: Spanned<FieldName>,
        field_type: QualifiedTypeReference,
        type_name: Qualified<CustomTypeName>,
    },

    #[error("Invalid operator used in type '{type_name:}' predicate: '{operator_name:}'")]
    InvalidOperatorInTypePredicate {
        type_name: Qualified<CustomTypeName>,
        operator_name: Spanned<OperatorName>,
    },
    #[error("Nested predicate used in type '{type_name:}'")]
    NestedPredicateInTypePredicate {
        type_name: Qualified<CustomTypeName>,
    },
    #[error(

View on GitHub (pinned to 724551b9ae)

Solutions

  1. Remove the single-value comparison on the predicate-typed field
  2. If you meant to combine filters, use boolean operators (`_and`/`_or`/`_not`) over the expression, not `_eq` on it
  3. Redesign the boolean expression type so its fields are comparable scalars or nested expressions used correctly

Example fix

// before
{"field": "userFilter", "operator": "_eq", "value": {...}}
// after: apply the nested expression directly
{"field": "user", "operator": "_and", "value": [{"field": "age", "operator": "_gt", "value": 18}]}
Defensive patterns

Strategy: type-guard

Validate before calling

// Guard: fields whose type is a predicate type must not be value-compared
if is_predicate_type(&field_type) {
    return Err("cannot compare predicate-typed field to a value".into());
}

Type guard

fn is_predicate_type(fr: &QualifiedTypeReference, expr_types: &HashSet<Qualified<CustomTypeName>>) -> bool {
    matches!(fr.underlying_type(), UnderlyingType::Named(n) if expr_types.contains(n))
}

Try / catch

if let Err(TypePredicateError::UnsupportedFieldComparisonToPredicateType { field_name, .. }) = result {
    // restructure using boolean combinators
}

Prevention

When it happens

Trigger: Applying `_eq`-style operators to a field typed as a boolean expression/predicate input; nesting a filter-expression field inside another comparison; accidental self-referential filter types in metadata.

Common situations: Mis-designed filterExpressionType that includes another expression type as a plain field; generic client code applying equality to every field including expression-typed ones.

Related errors

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