hasura/graphql-engine · error · TypePredicateError

unknown field '{field_name:}' used in predicate for type '{t

Error message

unknown field '{field_name:}' used in predicate for type '{type_name:}'

What it means

Thrown during metadata resolution when a type predicate (filterExpression) references a field that does not exist on the type being filtered. The resolver looks up every field name in the predicate against the resolved type's field set and rejects unknown names with the offending field and type.

Source

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

    pub lines_of: Vec<T>,
}

impl<T: Display> Display for SeparatedBy<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        for (index, elem) in self.lines_of.iter().enumerate() {
            elem.fmt(f)?;
            if index < self.lines_of.len() - 1 {
                writeln!(f)?;
            }
        }

        Ok(())
    }
}

#[derive(Debug, thiserror::Error)]
pub enum TypePredicateError {
    #[error("unknown field '{field_name:}' used in predicate for type '{type_name:}'")]
    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>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

Check the exact `field_name` and `type_name` in the message and open that type's field definitions
Fix the typo or rename the field in the predicate to a field that exists on `type_name`
If the field was removed intentionally, delete the predicate expression that references it
If the field lives on a related model, use a relationship-based predicate instead of a direct field reference

Example fix

// before: predicate references 'userNam' which does not exist
{"field": "userNam", "operator": "_eq", "value": "bob"}
// after
{"field": "userName", "operator": "_eq", "value": "bob"}

Defensive patterns

Strategy: validation

Validate before calling

// Before resolving, verify every predicate field exists on the type
let valid: HashSet<&str> = object_type
    .fields
    .keys()
    .map(|f| f.as_str())
    .collect();
for f in predicate.field_paths() {
    if !valid.contains(f) {
        return Err(format!("unknown field {f} on {}", object_type.name));
    }
}
Ok(())

Type guard

fn is_known_field(ty: &ObjectType, name: &str) -> bool {
    ty.fields.keys().any(|f| f.as_str() == name)
}

Try / catch

// On resolution failure, surface field/type to the user
if let Err(metadata_resolve::Error::TypePredicate(TypePredicateError::UnknownFieldInTypePredicate { field_name, type_name })) = result {
    return Err(format!("filter field {field_name} not on {type_name}"));
}

Prevention

Generate predicates from the type's field list rather than hand-writing them
Add a metadata lint step that cross-checks predicate fields against type fields

When it happens

Trigger: Defining a `filterExpressionType` / type predicate JSON that uses a field name not present on the object type it filters; renaming or deleting a model field without updating the predicate; typo in a field name inside a predicate expression.

Common situations: Renaming a column/field in the underlying model but leaving stale predicates in metadata; hand-written predicate JSON with typos; copy-pasting a predicate between types whose fields differ.

Related errors

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