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 command {command_name} is unknown.

What it means

A relationship argument mapping references an argument that the target command does not accept. For command-target relationships, every mapped target argument must match one of the command's declared arguments.

Source

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

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the target command's argument names in the command metadata and fix the mapping
2. Update mappings after any command argument rename
3. Ensure you are targeting the intended command

Example fix

// before
relationships:
  author:
    target: { command: AuthorById }
    argument_mappings:
      author_id: authorId  # command argument is 'author_id'
// after
argument_mappings:
  author_id: author_id

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

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

When it happens

Trigger: Defining argument mappings against a command whose argument list doesn't include the mapped name; command signature changed (argument renamed/removed).

Common situations: Command interface evolution between metadata versions; mappings written from stale docs; using model argument names for a command target.

Related errors

• unknown target command {command_name:} used in relationship
• target argument {argument_name} in argument mapping for rela
• The target argument {argument_name} of model {model_name} ha
• The target argument {argument_name} of command {command_name
• No mapping for target command argument {argument_name} in th

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