hasura/graphql-engine · warning · CommandPermissionIssue::CommandUsesRulesBasedAuthorization

the command {command_name} uses rules-based authorization so

Error message

the command {command_name} uses rules-based authorization so will not appear in the GraphQL schema

What it means

CommandUsesRulesBasedAuthorization warns that the command itself is authorized via rules-based authorization, which cannot be represented in the GraphQL schema, so the command will not appear as a GraphQL field. It is a resolution-stage warning that the command is effectively GraphQL-invisible.

Source

Thrown at v3/crates/metadata-resolve/src/stages/command_permissions/types.rs:70

pub enum CommandPermissionIssue {
    #[error(
        "Type error in preset argument {argument_name:} {}in command {command_name:}: {typecheck_issue:}", 
            {match role { Some(role) => format!("for role {role} "), None => String::new()}}) 
    ]
    CommandArgumentPresetTypecheckIssue {
        role: Option<Role>,
        command_name: Qualified<CommandName>,
        argument_name: ArgumentName,
        typecheck_issue: typecheck::TypecheckIssue,
    },
    #[error(
        "the object type {data_type} used as a return type for command {command_name} uses rules-based authorization so will not appear in the GraphQL schema"
    )]
    CommandReturnTypeUsesRulesBasedAuthorization {
        command_name: Qualified<CommandName>,
        data_type: Qualified<CustomTypeName>,
    },
    #[error(
        "the command {command_name} uses rules-based authorization so will not appear in the GraphQL schema"
    )]
    CommandUsesRulesBasedAuthorization {
        command_name: Qualified<CommandName>,
    },
    #[error(
        "the object type {argument_type} used in arguments for the command {command_name} uses rules-based authorization so any presets will not be applied in the GraphQL schema"
    )]
    CommandArgumentTypeUsesRulesBasedAuthorization {
        command_name: Qualified<CommandName>,
        argument_type: Qualified<CustomTypeName>,
    },
}

impl ShouldBeAnError for CommandPermissionIssue {
    fn should_be_an_error(&self, flags: &open_dds::flags::OpenDdFlags) -> bool {
        match self {
            CommandPermissionIssue::CommandArgumentPresetTypecheckIssue {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Switch the command's authorization to boolean-expression or backend-only permissions so it appears in the GraphQL schema
2. If the command must stay rules-based, expose its functionality through a different entry point (e.g. a model query or custom handler)
3. Suppress/acknowledge the warning if the command is intentionally GraphQL-hidden

Example fix

# before
command_permissions:
  my_command:
    rules: [...]   # rules-based

# after
command_permissions:
  my_command:
    filter: [...]  # boolean-expression based
# or backend_only: true

if command_permissions.is_rules_based() {
    log::warn!("command {} uses rules-based auth and will not appear in the GraphQL schema", command_name);
}

Capture as a warning from the resolve stage; do not abort, but track the command as GraphQL-invisible and adjust client queries accordingly.

When it happens

Trigger: Defining command permissions for a command using the rules-based authorization form (rules engine) instead of boolean expressions/backend-only; resolving metadata then emits this warning for that command.

Common situations: Adopting rules-based authorization globally and applying it to commands without realizing commands cannot be exposed in GraphQL under it; feature-flag rollout of rules-based auth hitting existing commands.

Related errors

• the object type {data_type} used as a return type for comman
• the object type {argument_type} used in arguments for the co
• no permission to select from command {command_name:}
• Session variable not found: {name}
• Condition {condition_hash} not found

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