hasura/graphql-engine · error · TypePredicateError

relationship '{relationship_name}' is used in predicate but

Error message

relationship '{relationship_name}' is used in predicate but does not exist in comparableRelationships in boolean expression '{boolean_expression_type_name}'

What it means

A predicate used a relationship for filtering, but that relationship is not listed in the boolean expression type's `comparableRelationships`. Only relationships explicitly marked comparable by the boolean expression type can be used inside predicates of that expression.

Source

Thrown at v3/crates/metadata-resolve/src/types/error.rs:489

    #[error("Nested predicate used in type '{type_name:}'")]
    NestedPredicateInTypePredicate {
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "no boolean expression found for type '{type_name:}' This is required when filtering a nested field. Please ensure the model you are filtering has a filterExpressionType defined."
    )]
    NoBooleanExpressionFields {
        field_name: Spanned<FieldName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "relationship '{relationship_name}' is used in predicate but does not exist for type '{type_name}'"
    )]
    UnknownRelationshipInTypePredicate {
        relationship_name: Spanned<RelationshipName>,
        type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "relationship '{relationship_name}' is used in predicate but does not exist in comparableRelationships in boolean expression '{boolean_expression_type_name}'"
    )]
    RelationshipNotComparableInTypePredicate {
        relationship_name: Spanned<RelationshipName>,
        boolean_expression_type_name: Qualified<CustomTypeName>,
    },
    #[error(
        "The model '{target_model_name:}' corresponding to the  relationship '{relationship_name:}' used in predicate for type '{type_name:}' is not defined"
    )]
    UnknownModelUsedInRelationshipTypePredicate {
        type_name: Qualified<CustomTypeName>,
        target_model_name: Qualified<ModelName>,
        relationship_name: RelationshipName,
    },
    #[error(
        "target source for model '{target_model_name:}' is required to resolve predicate with relationships for {source_type_name:}"
    )]
    TargetSourceRequiredForRelationshipPredicate {

View on GitHub (pinned to 724551b9ae)

Solutions

Open the boolean expression type named by `boolean_expression_type_name` and add the relationship to its `comparableRelationships` list
Verify the relationship name is spelled identically to the model's relationship declaration
Alternatively stop filtering via that relationship, or drop the custom expression type to use the generated default

Example fix

# before
types:
  UserBoolExpr:
    comparableRelationships: []
# after
types:
  UserBoolExpr:
    comparableRelationships: [articles]

Defensive patterns

Strategy: validation

Validate before calling

// Check the relationship is comparable per the expression type before filtering
if !bool_expr_type.comparable_relationships.contains(&relationship_name) {
    return Err("relationship not comparable in this boolean expression".into());
}

Type guard

fn is_comparable(e: &BooleanExpressionType, r: &RelationshipName) -> bool {
    e.comparable_relationships.contains(r)
}

Try / catch

if let Err(TypePredicateError::RelationshipNotComparableInTypePredicate { relationship_name, boolean_expression_type_name }) = result {
    // add relationship to comparableRelationships or filter differently
}

Prevention

When adding relationships, update comparableRelationships on custom expression types in the same change
Prefer default generated expression types unless you need restrictions

When it happens

Trigger: Adding a relationship to a model and filtering on it while the model's custom `filterExpressionType` doesn't include it in `comparableRelationships`; custom boolean expression types authored before the relationship existed.

Common situations: Custom filterExpressionType drifted out of sync with new relationships; team adds relationships but no one updates the expression type; migrating from default to custom expression types that omit comparableRelationships.

Related errors

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