hasura/graphql-engine · error · RelationshipError

source field {field_name} in field mapping for relationship

Error message

source field {field_name} in field mapping for relationship {relationship_name} on type {source_type} is unknown.

What it means

Indicates that a relationship's field mapping references a source field that does not exist on the source custom type. The resolver checks every field mapping's source field against the fields of the type that declares the relationship.

Source

Thrown at v3/crates/metadata-resolve/src/stages/object_relationships/error.rs:42

    #[error(
        "unknown target model {model_name:} used in relationship {relationship_name:} on type {type_name:}"
    )]
    UnknownTargetModelUsedInRelationship {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        model_name: Qualified<ModelName>,
    },

    #[error(
        "unknown target command {command_name:} used in relationship {relationship_name:} on type {type_name:}"
    )]
    UnknownTargetCommandUsedInRelationship {
        type_name: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        command_name: Qualified<CommandName>,
    },

    #[error(
        "source field {field_name} in field mapping for relationship {relationship_name} on type {source_type} is unknown."
    )]
    UnknownSourceFieldInRelationshipMapping {
        source_type: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        field_name: FieldName,
    },
    #[error(
        "target field {field_name} in field mapping for relationship {relationship_name} on type {source_type} to model {model_name} is unknown."
    )]
    UnknownTargetFieldInRelationshipMapping {
        source_type: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        model_name: Qualified<ModelName>,
        field_name: FieldName,
    },
    #[error(
        "target argument {argument_name} in argument mapping for relationship {relationship_name} on type {source_type} to model {model_name} is unknown."

View on GitHub (pinned to 724551b9ae)

Solutions

Check the field mapping entries of the relationship and confirm each source_field exists on the source type
Fix any typo or stale field name in the mapping
If the field was renamed, update the mapping to the new name or remove the mapping entry

Example fix

// before
type: article
fields: [id, title]
relationships:
  author:
    field_mappings:
      - source: author_id   # not a field on article
        target: { model: authors, field: id }
// after
fields: [id, title, author_id]
relationships:
  author:
    field_mappings:
      - source: author_id
        target: { model: authors, field: id }

Defensive patterns

Strategy: validation

Validate before calling

const typeFields = new Set(Object.keys(metadata.types[srcType].fields));
for (const m of rel.field_mappings ?? []) {
  if (!typeFields.has(m.source)) throw new Error(`unknown source field ${m.source} on ${srcType}`);
}

Try / catch

try { await applyMetadata(md); } catch (e) { if (/source field .* is unknown/.test(e.message)) { /* list type fields vs mappings */ } throw e; }

Prevention

Keep field mappings adjacent to the type definition in the same file/repo
Write a pre-apply schema cross-check script for source fields

When it happens

Trigger: Adding a field mapping like `{ source_field: id, target: ... }` where `id` is not a field declared on the source type; renaming a type field without updating its relationship mappings.

Common situations: Typos in source field names; schema drift after renaming or removing fields on the custom type; mappings copied from another type whose fields differ.

Related errors

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