hasura/graphql-engine · error · CommandsError::UnknownCommandArgumentType

the argument '{argument_name}' in command '{command_name}' h

Error message

the argument '{argument_name}' in command '{command_name}' has an unknown type: {argument_type}

What it means

UnknownCommandArgumentType is raised when a command argument references a type that cannot be resolved in the metadata's type system (not a known scalar, object, or predicate type). Argument types must resolve to TypeReference-known types; otherwise the command cannot be compiled.

Source

Thrown at v3/crates/metadata-resolve/src/stages/commands/error.rs:64

                    path: argument_name
                        .path
                        .clone()
                        .parent()
                        .append_key("type".into()),
                    message: format!("The argument type '{argument_type}' has not been defined",),
                }),
            ),

            _other => None,
        }
    }
}

#[derive(Debug, thiserror::Error)]
pub enum CommandsError {
    #[error("the following command is defined more than once: {name:}")]
    DuplicateCommandDefinition { name: Qualified<CommandName> },
    #[error(
        "the argument '{argument_name}' in command '{command_name}' has an unknown type: {argument_type}"
    )]
    UnknownCommandArgumentType {
        command_name: Qualified<CommandName>,
        argument_name: Spanned<ArgumentName>,
        argument_type: TypeReference,
    },
    #[error(
        "the following argument in command {command_name:} is defined more than once: {argument_name:}"
    )]
    DuplicateCommandArgumentDefinition {
        command_name: Qualified<CommandName>,
        argument_name: Spanned<ArgumentName>,
    },
    #[error("source for the following command is defined more than once: {command_name:}")]
    DuplicateCommandSourceDefinition {
        command_name: Qualified<CommandName>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the argument_type in the error and fix the spelling/name to match a declared type
2. Declare the missing object type or custom scalar in metadata if the command argument needs it
3. If the type was renamed (upgrade/migration), update the command argument to the new name

Example fix

# before
arguments:
  filter:
    type: UserFilterTypo   # declared type is UserFilter

# after
arguments:
  filter:
    type: UserFilter

// Verify every command argument type resolves before calling resolve
for cmd in &metadata.commands {
    for (arg_name, arg) in &cmd.arguments {
        if !known_types.contains(&arg.argument_type) {
            return Err(format!("command {} argument {arg_name} has unknown type {}", cmd.name, arg.argument_type));
        }
    }
}

fn argument_type_is_known(ty: &TypeReference, known: &HashSet<String>) -> bool {
    match ty { TypeReference::Named(n) => known.contains(n), _ => true }
}

Match UnknownCommandArgumentType { command_name, argument_name, argument_type } and suggest the closest known type name (fuzzy match) to speed up typo fixes.

When it happens

Trigger: Declaring a command argument whose argument_type TypeReference names a type that is undefined (typo, missing object type declaration, or unreferenced scalar), then running the commands resolve stage.

Common situations: Typos in argument type names; removing/renaming an object type without updating commands that use it; forgetting to declare a custom scalar; version upgrades renaming built-in types (e.g. predicate input names changing).

Related errors

• the following command is defined more than once: {name:}
• the following argument in command {command_name:} is defined
• source for the following command is defined more than once:
• unknown type {custom_type_name}
• The data type {data_type} has not been defined

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