hasura/graphql-engine · error · BooleanExpressionIssue::GraphqlFieldNameConflict

the boolean expression '{type_name}' has a GraphQL field nam

Error message

the boolean expression '{type_name}' has a GraphQL field name conflict between the '{name}' {name_source_1} and the '{name}' {name_source_2}. One of these will need to be renamed.

What it means

Two members of the boolean expression type (fields and/or relationships) produce the same GraphQL field name after applying naming/renaming rules. GraphQL object fields must be unique, so one must be renamed.

Source

Thrown at v3/crates/metadata-resolve/src/stages/boolean_expressions/types.rs:58

        boolean_expression_type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
        field_type: QualifiedTypeReference,
    },
    #[error(
        "the comparable field '{name}' is defined more than once in the boolean expression type '{type_name}'"
    )]
    DuplicateComparableFieldFound {
        type_name: Qualified<CustomTypeName>,
        name: FieldName,
    },
    #[error(
        "the comparable relationship '{name}' is defined more than once in the boolean expression type '{type_name}'"
    )]
    DuplicateComparableRelationshipFound {
        type_name: Qualified<CustomTypeName>,
        name: RelationshipName,
    },
    #[error(
        "the boolean expression '{type_name}' has a GraphQL field name conflict between the '{name}' {name_source_1} and the '{name}' {name_source_2}. One of these will need to be renamed."
    )]
    GraphqlFieldNameConflict {
        type_name: Qualified<CustomTypeName>,
        name: String,
        name_source_1: FieldNameSource,
        name_source_2: FieldNameSource,
    },
    #[error(
        "the type of the comparable field '{field_name}' on the boolean expresssion '{boolean_expression_type_name}' is a multidimensional array type: {field_type}. Multidimensional arrays are not supported in boolean expressions"
    )]
    MultidimensionalArrayComparableFieldNotSupported {
        boolean_expression_type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
        field_type: QualifiedTypeReference,
    },
    #[error(
        "the target model '{target_model_name}' of the relationship '{relationship_name}' does not have a boolean expression type defined"

View on GitHub (pinned to 724551b9ae)

Solutions

Rename one of the conflicting entries (field or relationship) in metadata so their GraphQL names differ
Check for graphql_config renames that create the collision and adjust them
Watch for camelCase normalization collisions between snake_case names differing only in underscores

Example fix

// before
fields:
  author_id: Uuid
relationships:
  - name: authorId   # conflicts after normalization with a field 'author_id' -> 'authorId'
// after
relationships:
  - name: author

Defensive patterns

Strategy: validation

Validate before calling

// Simulate GraphQL naming to detect collisions before resolve
use std::collections::BTreeSet;
let mut names = BTreeSet::new();
for f in be_type.comparable_fields.iter().map(|f| graphql_name(&f.name))
    .chain(be_type.comparable_relationships.iter().map(|r| graphql_name(&r.name))) {
    if !names.insert(f.clone()) {
        return Err(format!("GraphQL name conflict on {f}"));
    }
}

Type guard

fn graphql_name_conflicts(be_type: &BooleanExpressionType) -> Vec<String> {
    let mut seen: HashMap<String, usize> = HashMap::new();
    for n in be_type.graphql_member_names() { *seen.entry(n).or_default() += 1; }
    seen.into_iter().filter(|(_, c)| *c > 1).map(|(n, _)| n).collect()
}

Try / catch

if let BooleanExpressionIssue::GraphqlFieldNameConflict { type_name, name, name_source_1, name_source_2 } = &issue {
    eprintln!("rename the '{name}' {name_source_1} or {name_source_2} in {type_name}");
}

Prevention

Avoid giving a field and relationship the same name
Account for camelCase normalization and graphql_config renames when naming members
Add a naming-collision lint to metadata CI

When it happens

Trigger: A comparable field and a comparable relationship (or two entries after GraphQL name normalization/renaming) both resolve to the same GraphQL field name on the boolean expression type.

Common situations: A field `author` and a relationship also named `author`; renames applied via graphql_config causing a collision; name normalization (camelCase conversion) collapsing two distinct snake_case names into one.

Related errors

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