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

the object type {data_type} used as a return type for comman

Error message

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

What it means

CommandReturnTypeUsesRulesBasedAuthorization warns that a command's return object type uses rules-based authorization (row-level security rules evaluated via a command/rule engine) rather than backend-only/boolean expressions, so that type cannot be represented in the GraphQL schema. Commands returning such types are effectively dropped from the GraphQL API surface.

Source

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

    pub allow_execution: bool,
    pub argument_presets:
        BTreeMap<ArgumentName, (QualifiedTypeReference, ValueExpressionOrPredicate)>,
}

#[derive(Debug, thiserror::Error)]
#[allow(clippy::enum_variant_names)]
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>,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Change the return type's authorization from rules-based to boolean-expression/backend-only permissions so it can appear in the GraphQL schema
2. Or accept the type will not be exposed via GraphQL and query it through another mechanism
3. Re-model the command to return a different object type that does not use rules-based authorization

Example fix

# before
type_permissions:
  object_type: MonthlyUsage
  rules: [... ]   # rules-based; command returns MonthlyUsage

# after
type_permissions:
  object_type: MonthlyUsage
  filter: [...]   # boolean-expression based; command return appears in GraphQL

fn warn_if_return_type_rules_based(cmd: &Command, types: &TypePermissions) -> Option<String> {
    types.get(&cmd.return_type).filter(|p| p.is_rules_based())
        .map(|_| format!("command {} return type uses rules-based auth; hidden from GraphQL", cmd.name))
}

Treat as a warning: log it and continue; do not fail the pipeline, but mark the command as absent from the GraphQL schema in docs.

When it happens

Trigger: Declaring a command whose return type is an object type whose type permissions use rules-based authorization; metadata resolution emits this warning during the command permissions stage.

Common situations: Migrating to rules-based authorization on an object type that is also a command return type; enabling the rules-based auth feature flag on existing types without realizing commands returning them stop appearing in GraphQL.

Related errors

• the command {command_name} uses rules-based authorization so
• 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/c1864f1bb6c05295. Report an issue: GitHub.