hasura/graphql-engine · error · RelationshipError

Mapping for source field {field_name} already exists in the

Error message

Mapping for source field {field_name} already exists in the relationship {relationship_name} on type {type_name}

What it means

The same source field is used in more than one field mapping within a single relationship. Each source field may only be mapped once per relationship.

Source

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

    #[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(
        "target argument {argument_name} in argument mapping for relationship {relationship_name} on type {source_type} to command {command_name} is unknown."
    )]
    UnknownTargetCommandArgumentInRelationshipMapping {
        source_type: Qualified<CustomTypeName>,
        relationship_name: RelationshipName,
        command_name: Qualified<CommandName>,
        argument_name: ArgumentName,
    },
    #[error(
        "Mapping for source field {field_name} already exists in the relationship {relationship_name} on type {type_name}"
    )]
    MappingExistsInRelationship {
        type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
        relationship_name: RelationshipName,
    },
    #[error(
        "The target argument {argument_name} of model {model_name} has been mapped more than once in the relationship {relationship_name} on type {type_name}"
    )]
    ModelArgumentMappingExistsInRelationship {
        argument_name: ArgumentName,
        model_name: Qualified<ModelName>,
        relationship_name: RelationshipName,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "The target argument {argument_name} of command {command_name} has been mapped more than once in the relationship {relationship_name} on type {type_name}"

View on GitHub (pinned to 724551b9ae)

Solutions

1. Find duplicate source field entries in the relationship's field_mappings and keep only one
2. If you need to map the same source to multiple targets, that is not supported — remove the extra entry
3. Lint metadata for duplicate mapping keys before applying

Example fix

// before
field_mappings:
  - source: author_id
    target: { model: authors, field: id }
  - source: author_id
    target: { model: users, field: id }
// after
field_mappings:
  - source: author_id
    target: { model: authors, field: id }

const sources = (rel.field_mappings ?? []).map(m => m.source);
const dupes = sources.filter((s, i) => sources.indexOf(s) !== i);
if (dupes.length) throw new Error(`duplicate source fields: ${dupes}`);

try { await applyMetadata(md); } catch (e) { if (/Mapping for source field .* already exists/.test(e.message)) { /* dedupe */ } throw e; }

When it happens

Trigger: Defining two field mapping entries with identical source_field values on the same relationship (often via YAML anchors or duplicated blocks).

Common situations: Copy-paste duplication in metadata YAML/JSON; merging metadata files that each add a mapping for the same source field.

Related errors

• source field {field_name} in field mapping for relationship
• target field {field_name} in field mapping for relationship
• The target argument {argument_name} of model {model_name} ha
• the field '{field_name}' is defined more than once in the co
• the relationship '{relationship_name}' is defined more than

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