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

the following command is defined more than once: {name:}

Error message

the following command is defined more than once: {name:}

What it means

CommandsError::DuplicateCommandDefinition is raised during the commands resolution stage when two command definitions share the same qualified command name. Command names become unique API entry points, so duplicates are rejected.

Source

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

                .append(Step {
                    subgraph: Some(command_name.subgraph.clone()),
                    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 {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename one of the commands (e.g. prefix with agent/domain) so the qualified name is unique
2. Search all metadata sources (agents, modules) for the command name and delete the stale duplicate
3. Ensure subgraph namespaces are set so qualified names do not collide

Example fix

# before
commands:
  - name: syncUser   # in agent A
  - name: syncUser   # in agent B

# after
commands:
  - name: agentA_syncUser
  - name: agentB_syncUser

fn assert_unique_command_names(commands: &[Command]) -> Result<(), String> {
    let mut seen = HashSet::new();
    for c in commands {
        if !seen.insert(c.name.clone()) {
            return Err(format!("duplicate command: {}", c.name));
        }
    }
    Ok(())
}

Match CommandsError::DuplicateCommandDefinition { name } and report the colliding qualified name plus the originating files to guide dedupe.

When it happens

Trigger: Defining two commands with the same Qualified<CommandName> — same name in the same namespace/agent — anywhere in the metadata (multiple files, agents, or subgraphs).

Common situations: Copying a command definition to another agent/file without renaming; merging metadata from multiple teams; two subgraphs independently defining the same command name after enabling federated namespaces.

Related errors

• the boolean expression type with name {type_name} is defined
• the following argument in command {command_name:} is defined
• source for the following command is defined more than once:
• error in getting server feature flags %w
• Cannot add query root field {0} as it already in use

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