hasura/graphql-engine · error · TypePredicateError

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

Error message

unknown field '{field_name}' for type '{type_name}' used in target mapping for relationship '{relationship_name}'

What it means

While resolving a relationship's target mapping, the resolver found a field name on the target type that does not exist. Relationship target mappings map source fields to target-model fields; any target-side field name that is not defined on the target type triggers this error.

Source

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

    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>,
    },
    #[error(
        "field '{field_name:}' could not be found in boolean expression type for object type '{type_name:}'"
    )]
    BooleanExpressionFieldNotFound {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Open the relationship named `relationship_name` and check its target mapping entries
2. Correct each `field` on the target side to a field that exists on `type_name` (the target type)
3. If the target field was removed, remap to an equivalent existing field or drop the mapping entry
4. Add metadata validation in CI to catch dangling relationship mappings after model changes

Example fix

# before
relationships:
  - name: articles
    targetMapping: {author: authorID}   # authorID not a field of target
# after
relationships:
  - name: articles
    targetMapping: {author: author_id}  # actual field name

// Validate relationship target mappings against the target type's fields
for (src, tgt) in &relationship.target_mapping {
    if !target_type.fields.contains_key(tgt) {
        return Err(format!("target field {tgt} not on {}", target_type.name));
    }
}

fn target_field_exists(t: &ObjectType, f: &FieldName) -> bool {
    t.fields.contains_key(f)
}

if let Err(Error::UnknownFieldInModelRelationshipTargetMapping { field_name, type_name, relationship_name }) = result {
    return Err(format!("relationship {relationship_name}: {field_name} missing on {type_name}"));
}

When it happens

Trigger: Declaring a relationship with `targetMapping: {field: <targetField>}` where `<targetField>` is not a field of the target model; renaming or removing target-model fields after the relationship was defined.

Common situations: Target model evolved (field renamed/removed) but relationship mappings kept the old name; typos in relationship mappings; copy-pasting mappings between models with different fields.

Related errors

• Target model {model_name:} not found, referenced in relation
• the target model '{target_model_name}' of the relationship '
• the type {unknown_ndc_field_type_name:} is not defined as an
• the field {field_name:} in {type_name:} should have the type
• Field type {field_type} could not be found in field {field_n

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