hasura/graphql-engine · error · CommandsIssue::GraphQlRootFieldAlreadyInUse

Cannot add the command {command_name:} to GraphQL schema: {e

Error message

Cannot add the command {command_name:} to GraphQL schema: {error:}

What it means

Raised when adding a command's root field to the GraphQL schema collides with an existing root field (DuplicateRootFieldError). The GraphQL root (query/mutation) must have unique field names across commands, tables, and other root fields.

Source

Thrown at v3/crates/metadata-resolve/src/stages/commands/types.rs:88

    #[error(
        "An issue occurred while mapping arguments in the command {command_name:} to the function {function_name:} in the data connector {data_connector_name:}: {issue:}"
    )]
    FunctionArgumentMappingIssue {
        data_connector_name: Qualified<DataConnectorName>,
        command_name: Qualified<CommandName>,
        function_name: FunctionName,
        issue: ArgumentMappingIssue,
    },
    #[error(
        "An issue occurred while mapping arguments in the command {command_name:} to the procedure {procedure_name:} in the data connector {data_connector_name:}: {issue:}"
    )]
    ProcedureArgumentMappingIssue {
        data_connector_name: Qualified<DataConnectorName>,
        command_name: Qualified<CommandName>,
        procedure_name: ProcedureName,
        issue: ArgumentMappingIssue,
    },
    #[error("Cannot add the command {command_name:} to GraphQL schema: {error:}")]
    GraphQlRootFieldAlreadyInUse {
        command_name: Qualified<CommandName>,
        error: DuplicateRootFieldError,
    },
    #[error("Command '{command_name}' has an invalid output type '{output_type}'")]
    InvalidCommandOutputType {
        command_name: Qualified<CommandName>,
        output_type: TypeReference,
    },
}

impl ShouldBeAnError for CommandsIssue {
    fn should_be_an_error(&self, flags: &open_dds::flags::OpenDdFlags) -> bool {
        match self {
            CommandsIssue::GraphQlRootFieldAlreadyInUse { .. } => {
                flags.contains(open_dds::flags::Flag::RequireUniqueCommandGraphqlNames)
            }
            CommandsIssue::InvalidCommandOutputType { .. } => {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename the conflicting command's root field in its graphql config
2. Check other commands/tables for the same field name
3. Rebuild metadata

Example fix

// before
command A { graphql: "myField" }
command B { graphql: "myField" }
// after
command A { graphql: "myField" }
command B { graphql: "myOtherField" }

// Collect all configured root fields and assert uniqueness before resolving
let mut seen = HashSet::new();
for f in all_root_fields { assert!(seen.insert(f.clone()), "duplicate root field {f}"); }

Catch GraphQlRootFieldAlreadyInUse and suggest renaming the command's graphql field.

When it happens

Trigger: Two commands (or a command and a table) configured with the same GraphQL root field name for the same operation type.

Common situations: Copying a command definition without changing its graphql root field, or a command name that clashes with an auto-generated table root field.

Related errors

• Command '{command_name}' has an invalid output type '{output
• error in getting server feature flags %w
• parsing 'admin_secrets' from config.yaml / environment varia
• Field mapping not found for the field {field_name:} of type
• Object type '{type_name}' not found

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