hasura/graphql-engine · error · NamedArgumentError

argument '{argument_name}' in {source} has an error: {error}

Error message

argument '{argument_name}' in {source} has an error: {error}

What it means

This is a wrapper error from the arguments resolution stage: while resolving the arguments attached to a command or model, an underlying ArgumentError occurred for the named argument. The wrapper adds context (which argument, in which source — e.g. a command name) so the developer can locate the failing piece of metadata; the nested {error} describes the specific problem (unknown type, invalid default, etc.).

Source

Thrown at v3/crates/metadata-resolve/src/stages/arguments/error.rs:8

use super::types::ArgumentSource;
use crate::Qualified;
use crate::stages::boolean_expressions;
use crate::types::error::ContextualError;
use open_dds::{arguments::ArgumentName, types::CustomTypeName};

#[derive(Debug, thiserror::Error)]
#[error("argument '{argument_name}' in {source} has an error: {error}")]
pub struct NamedArgumentError {
    pub source: ArgumentSource,
    pub argument_name: ArgumentName,
    pub error: ArgumentError,
}

impl ContextualError for NamedArgumentError {
    fn create_error_context(&self) -> Option<error_context::Context> {
        self.error.create_error_context()
    }
}

#[derive(Debug, thiserror::Error)]
#[allow(clippy::large_enum_variant)]
pub enum ArgumentError {
    #[error("{0}")]
    BooleanExpressionError(#[from] boolean_expressions::BooleanExpressionError),
    #[error("Unknown type: {type_name}")]

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the nested {error} message — it identifies the actual problem with the argument (e.g. unknown argument type).
2. Fix the named argument's definition in the source indicated (usually a typo in the type name or a missing type declaration).
3. Re-apply the metadata and confirm the arguments stage passes.

Example fix

// before
command: get_user
arguments:
  id:
    type: Uuid   # typo: undeclared type
// after
command: get_user
arguments:
  id:
    type: Uuid  # declared correctly in the metadata types section

// Pre-flight: every argument type should be declared
fn args_reference_declared_types(args: &ArgumentMap, types: &TypeGraph) -> Result<(), String> {
    for (name, arg) in args {
        if types.resolve(&arg.type_name).is_none() {
            return Err(format!("argument '{name}' references undeclared type"));
        }
    }
    Ok(())
}

match result {
    Err(e) if e.is::<NamedArgumentError>() => {
        // inspect e.argument_name, e.source, and the nested e.error for actionable detail
        report_argument_issue(&e.source, &e.argument_name, &e.error);
    }
    other => other,
}

When it happens

Trigger: Declaring an argument on a command or model whose argument metadata fails one of the argument-stage validations (e.g. referencing an undeclared type for the argument, or an invalid description/default), surfaced as NamedArgumentError wrapping the inner ArgumentError.

Common situations: Adding an argument that references a type not defined in metadata; typos in argument type names; inconsistent argument definitions after metadata refactors; upgrading metadata API versions where argument semantics tightened.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• argument {argument_name:?} has an issue: {issue:?}
• the target model '{target_model_name}' of the relationship '
• the following argument in command {command_name:} is defined
• the fieldName for argumentsInput needs to be defined in Grap
• unknown target command {command_name:} used in relationship

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