hasura/graphql-engine · error · ArgumentPresetExecutionError

argument mapping not found for {argument_name}

Error message

argument mapping not found for {argument_name}

What it means

ArgumentMappingNotFound is thrown when the planner needs an argument's mapping (how a GraphQL/external argument maps to the underlying source parameter) for the named ArgumentName and it does not exist. This is a metadata-completeness error: every referenced argument must have a mapping entry.

Source

Thrown at v3/crates/plan/src/query/arguments.rs:394

    )]
    IllegalCharactersInHeaderValue,
    #[error("Model source not found for model '{model_name}'")]
    ModelSourceNotFound { model_name: Qualified<ModelName> },
    #[error("Model permissions for model {model_name} not found for role {role}")]
    ModelArgumentPresetsNotFound {
        role: Role,
        model_name: Qualified<ModelName>,
    },
    #[error("command {command_name} does not have a source defined")]
    CommandSourceNotFound {
        command_name: Qualified<CommandName>,
    },
    #[error("command permissions for command {command_name} not found for role {role}")]
    CommandArgumentPresetsNotFound {
        command_name: Qualified<CommandName>,
        role: Role,
    },
    #[error("argument mapping not found for {argument_name}")]
    ArgumentMappingNotFound { argument_name: ArgumentName },
    #[error("type mapping not found for object {object_type_name}")]
    TypeMappingNotFound {
        object_type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "no data connector field mapping found for field '{field_name}' of object type '{object_type_name}'"
    )]
    FieldMappingNotFound {
        object_type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
    },
    #[error(
        "no field definition found for field '{field_name}' of object type '{object_type_name}'"
    )]
    FieldDefinitionNotFound {
        object_type_name: Qualified<CustomTypeName>,
        field_name: FieldName,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Add a mapping entry for the named argument in the relevant command/model metadata
2. Check for spelling/case mismatch between the argument used in the query and the mapping key
3. Regenerate or update mappings after changing connector argument names
4. Run metadata validation before deploying

Example fix

// before
{"argumentMappings":{"id":{}}}
// after
{"argumentMappings":{"id":{},"email":{}}}

fn argument_mapping_exists(mappings: &BTreeMap<ArgumentName, _>, arg: &ArgumentName) -> bool {
    mappings.contains_key(arg)
}

fn is_argument_mapping_not_found(e: &ArgumentPresetExecutionError) -> bool {
    matches!(e, ArgumentPresetExecutionError::ArgumentMappingNotFound { .. })
}

match result {
    Err(PlanError::Arguments(ArgumentPresetExecutionError::ArgumentMappingNotFound { argument_name })) => {
        bad_request(format!("no mapping for argument {argument_name}"));
    }
    other => other,
}

When it happens

Trigger: A query or command definition references an argument (e.g. 'limit', 'where', or a custom argument) that has no mapping defined in the argument mappings section of metadata during preset resolution.

Common situations: Adding an argument to a command/model type but forgetting its mapping; renaming an argument in one place only; upgrading a connector whose argument names changed while metadata kept old names.

Related errors

• argument {argument_name:?} has an issue: {issue:?}
• parsing 'admin_secrets' from config.yaml / environment varia
• expected 0 arguments, found: %v
• Serde error: {error}
• Condition {condition_hash} not found

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