hasura/graphql-engine · error · TypePredicateError

field '{field_name:}' of type '{type_name:}' is an array typ

Error message

field '{field_name:}' of type '{type_name:}' is an array type and cannot be used in a nested field predicate

What it means

A nested field predicate tried to descend into a field that is an array (list) type. Nested predicates only traverse into object/structured fields; array-typed fields require dedicated array operators (like `_contains`) and cannot be navigated as if they were nested objects.

Source

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

    UnknownFieldInTypePredicate {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "field '{field_name:}' used in predicate for type '{type_name:}' could not be found in boolean expression {boolean_expression_type}"
    )]
    TypePredicateFieldNotFoundInBooleanExpression {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
        boolean_expression_type: Qualified<CustomTypeName>,
    },

    #[error("field '{field_name:}' could not be found in field mappings for type '{type_name:}'")]
    UnknownFieldInFieldMappings {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "field '{field_name:}' of type '{type_name:}' is an array type and cannot be used in a nested field predicate"
    )]
    ArrayFieldInNestedFieldPredicate {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "unknown field '{field_name}' for type '{type_name}' used in target mapping for relationship '{relationship_name}'"
    )]
    UnknownFieldInModelRelationshipTargetMapping {
        field_name: FieldName,
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },
    #[error("boolean expression '{boolean_expression_name:}' not found")]
    BooleanExpressionNotFound {
        boolean_expression_name: Qualified<CustomTypeName>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

Stop descending into `field_name` and instead apply an array operator directly to it (e.g. `_contains`, `_any`/`_all` style operators your connector supports)
If the field should be scalar-navigable, change its type from a list to a single object in the model
Filter the scalar fields of the array elements via the connector's array-comparison operators rather than nested paths

Example fix

// before
{"field": "tags", "operator": "_nested", "value": {"field": "name", "operator": "_eq", "value": "hot"}}
// after
{"field": "tags", "operator": "_contains", "value": {"name": "hot"}}

Defensive patterns

Strategy: type-guard

Validate before calling

// Reject nested descent into array-typed fields before building the predicate
if field_type.underlying_type().is_array() {
    return Err("cannot nest into array field; use an array operator".into());
}

Type guard

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

Try / catch

if let Err(TypePredicateError::ArrayFieldInNestedFieldPredicate { field_name, .. }) = result {
    // rewrite as an array-operator predicate
}

Prevention

Check a field's cardinality before writing nested predicates
Prefer array operators (_contains etc.) for list fields

When it happens

Trigger: Building a filter like `{field: {path: {to: {array_field: {nested: ...}}}}}` where `array_field` is a list type; writing `relationship.field` style nested predicates through a list column.

Common situations: Treating a JSON/array column as a nested object in filters; assuming nested predicates work through array relationships; model changes turning an object field into a list field.

Related errors

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