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 an array type and therefore cannot be compared to a single value

What it means

A field comparison against a single value (e.g. `_eq`) was applied to a field of array type. Arrays cannot be ordered-compared to a single scalar; they require array-specific operators such as `_contains` or dedicated array comparison support.

Source

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

    },
    #[error(
        "the source data connector {data_connector:} for type {type_name:} has not been defined"
    )]
    UnknownTypeDataConnector {
        type_name: Qualified<CustomTypeName>,
        data_connector: Qualified<DataConnectorName>,
    },
    #[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 {

View on GitHub (pinned to 724551b9ae)

Solutions

Replace the single-value comparison with an array operator (`_contains`, or the connector's array comparison)
If the field should be scalar, fix the model's field type from list to scalar
Filter on an element expression supported by your connector instead of the array itself

Example fix

// before
{"field": "tags", "operator": "_eq", "value": "hot"}
// after
{"field": "tags", "operator": "_contains", "value": ["hot"]}

Defensive patterns

Strategy: type-guard

Validate before calling

// Guard: never single-value-compare array fields
if field_type.underlying_type().is_array() {
    return Err("use an array operator for list fields".into());
}

Type guard

fn is_array_type(fr: &QualifiedTypeReference) -> bool {
    matches!(fr.underlying_type(), UnderlyingType::List(_))
}

Try / catch

if let Err(TypePredicateError::UnsupportedFieldComparisonToArrayType { field_name, .. }) = result {
    // switch to _contains or another array operator
}

Prevention

Build filter UIs that choose operators by field cardinality
Track which model fields are lists and avoid _eq on them

When it happens

Trigger: Using `_eq`, `_lt`, `_gt` etc. on a list-typed field (`field_type` is a list reference); predicates generated by clients that assume scalar fields where the model now has arrays.

Common situations: Model schema changes turning a scalar column into an array/JSON column; generic filter builders applying equality to every field; misunderstanding which operators apply to arrays.

Related errors

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