hasura/graphql-engine · error · RelationshipFieldMappingError

Type mapping not found for the type name {type_name:} while

Error message

Type mapping not found for the type name {type_name:} while executing the relationship {relationship_name:}

What it means

RelationshipFieldMappingError::TypeMappingNotFoundForRelationship occurs while planning a relationship join: the target (or source) type of the relationship has no type mapping in the data connector's schema, so the join columns cannot be resolved. It names both the missing type and the relationship being executed.

Source

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

                Field::Column {
                    column: ndc_column_name.clone(),
                    fields: None,
                    arguments: BTreeMap::new(),
                },
            );
            SourceFieldAlias(internal_alias)
        }
        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(

View on GitHub (pinned to 724551b9ae)

Solutions

Check the relationship's type names against type_mappings in the source's schema and correct mismatches
Reload the source metadata so type mappings refresh after schema changes
Recreate the relationship via the console/CLI so it references current type names
Ensure both sides of the relationship are tracked in the same source (or configured for cross-source)

Example fix

// before
relationship: { source_type: "User", target_type: "Posts" }  // mapping is "Post"
// after
relationship: { source_type: "User", target_type: "Post" }

Defensive patterns

Strategy: validation

Validate before calling

// Verify both endpoint types of a relationship are mapped before use
fn relationship_types_mapped(rel: &Relationship, schema: &Schema) -> bool {
    schema.type_mappings.contains_key(&rel.source_type) && schema.type_mappings.contains_key(&rel.target_type)
}

Try / catch

Catch TypeMappingNotFoundForRelationship during planning and flag the relationship in metadata as misconfigured rather than retrying.

Prevention

Create relationships via CLI/console instead of hand-editing JSON
Run consistency checks after renames
Test nested selections after every schema migration

When it happens

Trigger: Defining a relationship in metadata whose source or target model's type name has no type_mapping in the source's schema, then executing a query that traverses that relationship (nested selection).

Common situations: Renaming a model/type without updating relationship definitions; relationships between types in different data sources without proper source configuration; stale metadata after connector schema evolution; manually authored relationship mappings with wrong type names.

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

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