hasura/graphql-engine · error · RelationshipError

target argument {argument_name} in argument mapping for rela

Error message

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

What it means

A relationship argument mapping references an argument that the target model does not accept. For model-target relationships, every mapped target argument must exist among the model's arguments.

Source

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

    #[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(
        "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(

View on GitHub (pinned to 724551b9ae)

Solutions

Inspect the target model's declared arguments and fix the argument name in the mapping
If the argument was renamed, update all relationship mappings referencing the old name
Switch the relationship target to the correct model if you meant a different one

Example fix

// before
argument_mappings:
  author_id: id   # model argument is 'author_id'
// after
argument_mappings:
  author_id: author_id

Defensive patterns

Strategy: validation

Validate before calling

const modelArgs = new Set(models[targetModel].arguments?.map(a => a.name) ?? []);
for (const [k, v] of Object.entries(rel.argument_mappings ?? {})) {
  if (!modelArgs.has(v)) throw new Error(`model ${targetModel} has no argument ${v}`);
}

Try / catch

try { await applyMetadata(md); } catch (e) { if (/target argument .* to model .* is unknown/.test(e.message)) { /* show model args */ } throw e; }

Prevention

Document each model's arguments next to relationship definitions
Add a CI check that argument mappings reference declared model arguments

When it happens

Trigger: Using `argument_mappings`/target argument names that are not declared on the target model (e.g., mapping to `id` when the model only takes `author_id`).

Common situations: Model argument renames; copy-pasting mappings from a command-based relationship to a model-based one where argument names differ; version drift in the model definition.

Related errors

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