hasura/graphql-engine · error · RelationshipFieldMappingError

Field mapping not found for the field {field_name:} of type

Error message

Field mapping not found for the field {field_name:} of type {type_name:} while executing the relationship {relationship_name:}

What it means

RelationshipFieldMappingError::FieldMappingNotFoundForRelationship is thrown when resolving a relationship's join keys: a field referenced by the relationship mapping (field_name on type_name) has no entry in the type's field mappings. The relationship cannot be executed because the column mapping is incomplete.

Source

Thrown at v3/crates/plan/src/query/relationships.rs:630

        Some(field_alias) => SourceFieldAlias(field_alias.to_string()),
    }
}

fn make_hasura_phantom_field(ndc_column_name: &DataConnectorColumnName) -> String {
    format!("__hasura_phantom_field__{}", ndc_column_name.as_str())
}

#[derive(Debug, thiserror::Error)]
pub enum RelationshipFieldMappingError {
    #[error(
        "Type mapping not found for the type name {type_name:} while executing the relationship {relationship_name:}"
    )]
    TypeMappingNotFoundForRelationship {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
    },

    #[error(
        "Field mapping not found for the field {field_name:} of type {type_name:} while executing the relationship {relationship_name:}"
    )]
    FieldMappingNotFoundForRelationship {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        field_name: FieldName,
    },
}

pub fn get_relationship_field_mapping_of_field_name(
    type_mappings: &BTreeMap<Qualified<CustomTypeName>, metadata_resolve::TypeMapping>,
    type_name: &Qualified<CustomTypeName>,
    relationship_name: &RelationshipName,
    field_name: &FieldName,
) -> Result<metadata_resolve::FieldMapping, RelationshipFieldMappingError> {
    let type_mapping = type_mappings.get(type_name).ok_or_else(|| {
        RelationshipFieldMappingError::TypeMappingNotFoundForRelationship {
            type_name: type_name.clone(),

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify every field in the relationship's column mapping exists in the type's field_mappings
2. Fix typos or renamed fields in the relationship definition
3. Reload/refresh the source schema and recreate the relationship
4. If a join key is genuinely needed, add the corresponding field to the connector schema/type mapping

Example fix

// before
column_mapping: { "authorId": "author_id" }  // type maps field "author_id"
// after
column_mapping: { "author_id": "author_id" }

for (src, tgt) in &rel.column_mapping {
    assert!(source_fields.contains(src) && target_fields.contains(tgt),
        "join key {src}/{tgt} missing from field mappings");
}

Catch FieldMappingNotFoundForRelationship and report the relationship name plus missing field for metadata repair.

When it happens

Trigger: A relationship whose column_mapping references a field (e.g. author_id) that does not exist in the type mapping's field_mappings of the source or target type; typically after renaming a column or writing the mapping by hand.

Common situations: Column renames in the database not propagated to relationship metadata; manual JSON editing of relationships with typos; relationships created against an older schema version; computed fields used as join keys without mappings.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Type mapping not found for the type name {type_name:} while
• Relationship '{name}' is either remote or not having 'relati
• the relationship '{relationship_name}' is defined more than
• the comparable relationship '{relationship_name}' for the op
• the comparable relationship '{relationship_name}' for the op

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