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

source for the following command is defined more than once:

Error message

source for the following command is defined more than once: {command_name:}

What it means

DuplicateCommandSourceDefinition is raised when a single command has more than one source block defined (e.g. multiple data connector sources or multiple handler entries). A command must have exactly one source of truth; multiple source definitions are ambiguous and rejected by the commands stage.

Source

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

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>,
    },
    #[error(
        "the source data connector {data_connector:} for command {command_name:} has not been defined"
    )]
    UnknownCommandDataConnector {
        command_name: Qualified<CommandName>,
        data_connector: Qualified<DataConnectorName>,
    },
    #[error(
        "the mapping for type {type_name:} in command {command_name:} is defined more than once"
    )]
    DuplicateTypeMappingDefinitionInCommandSource {
        command_name: Qualified<CommandName>,
        type_name: CustomTypeName,
    },
    #[error("command source is required for command '{command_name:}' to resolve argument preset")]

View on GitHub (pinned to 724551b9ae)

Solutions

Inspect the command named in the error and remove the extra source so exactly one remains
If using YAML anchors or programmatic merging, ensure the source key is replaced, not appended
After switching connectors, delete the previous source block from the command

Example fix

# before
commands:
  - name: getUser
    source:
      dataConnector: pg
    source:            # duplicate
      dataConnector: mongo

# after
commands:
  - name: getUser
    source:
      dataConnector: pg

Defensive patterns

Strategy: validation

Validate before calling

if let Some(cmd) = metadata.command(&name) {
    if cmd.sources.len() > 1 {
        return Err(format!("command {name} has {} source definitions; expected exactly 1", cmd.sources.len()));
    }
}

Try / catch

Match DuplicateCommandSourceDefinition { command_name } and report that the command must keep exactly one source block; include the command's file location if tracked.

Prevention

When migrating a command between connectors, replace the source block rather than adding a second one
Avoid YAML anchors that inject a default source into commands that define their own
Assert single-source invariants in programmatic metadata builders

When it happens

Trigger: Declaring a command with both an inline data connector source and another source entry (e.g. two source keys, or a source plus an inherited/merged one from YAML anchors or programmatic metadata merging).

Common situations: Metadata templating/merging producing two sources for one command; switching a command from one connector to another and leaving the old source in place; YAML merge keys combining defaults with an explicit source.

Related errors

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