hasura/graphql-engine · error · TypePredicateError

field '{field_name:}' could not be found in field mappings f

Error message

field '{field_name:}' could not be found in field mappings for type '{type_name:}'

What it means

The metadata resolver could not find the named field in the field mappings of the given type while resolving a predicate. Field mappings connect logical field names to underlying data-source representations; a predicate field missing from these mappings cannot be translated into a data request.

Source

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

}

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the field mappings for `type_name` in your metadata and confirm which field names are mapped
2. Add or restore a mapping entry for `field_name`, or correct the predicate to use a mapped field
3. If the field is computed/derived, ensure its mapping kind (e.g. column vs computed) is properly defined

Example fix

# before: predicate uses unmapped field
filters: {field: display_name, op: _eq, value: "x"}
# after: map it or filter a mapped field
fields:
  display_name:
    type: string
    mapping: {column: display_name}
filters: {field: display_name, op: _eq, value: "x"}

// Check field mappings before resolving predicates
if !type_mappings.contains_key(&field_name) {
    return Err(format!("field {field_name} missing from mappings of {type_name}"));
}

fn is_mapped(mappings: &BTreeMap<FieldName, FieldMapping>, f: &FieldName) -> bool {
    mappings.contains_key(f)
}

if let Err(TypePredicateError::UnknownFieldInFieldMappings { field_name, type_name }) = result {
    return Err(format!("{field_name} not mapped on {type_name}"));
}

When it happens

Trigger: A predicate or mapping-dependent resolution step looks up a field name in `type_name`'s field mappings and it is absent — e.g. after mappings were pruned, renamed, or the field is purely virtual/computed with no mapping.

Common situations: Renaming mapped field names in metadata without updating predicates; fields added to predicates but never mapped to a column; connector-specific mappings missing after a connector update.

Related errors

• the type {unknown_ndc_field_type_name:} is not defined as an
• metadata is not consistent: {error}
• An issue occurred while mapping arguments in the model {mode
• the type {unknown_ndc_type:} is not defined as an object typ
• ndc validation error: {0}

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