hasura/graphql-engine · error · RelationshipError

target field {field_name} in field mapping for relationship

Error message

target field {field_name} in field mapping for relationship {relationship_name} on type {source_type} to model {model_name} is unknown.

What it means

A relationship field mapping points at a target field that does not exist on the target model. The resolver verifies the `field_name` in each mapping against the target model's fields.

Source

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

    #[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."
    )]
    UnknownTargetModelArgumentInRelationshipMapping {
        source_type: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        model_name: Qualified<ModelName>,
        argument_name: ArgumentName,
    },
    #[error(

View on GitHub (pinned to 724551b9ae)

Solutions

Confirm the target model in the mapping and inspect its actual fields
Correct the target field name in the field mapping
If the target field was removed, re-map to an existing field or drop the mapping

Example fix

// before
field_mappings:
  - source: author_id
    target: { model: authors, field: authorId } # model defines 'id'
// after
field_mappings:
  - source: author_id
    target: { model: authors, field: id }

Defensive patterns

Strategy: validation

Validate before calling

const modelFields = new Set(models[targetModel].fields.map(f => f.name));
for (const m of rel.field_mappings ?? []) {
  if (!modelFields.has(m.target.field)) throw new Error(`unknown target field ${m.target.field} on model ${targetModel}`);
}

Try / catch

try { await applyMetadata(md); } catch (e) { if (/target field .* is unknown/.test(e.message)) { /* diff model fields vs mapping */ } throw e; }

Prevention

Regenerate model field lists whenever the underlying schema changes
Validate mappings against the live model schema in CI

When it happens

Trigger: Mapping to a target model field that is not defined on the target model (typo, renamed field, wrong model chosen as target).

Common situations: Target model schema changed (field renamed/removed) but relationship mappings weren't updated; mappings authored against a different version of the model.

Related errors

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