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 for type '{type_name}'

What it means

A predicate references a relationship by name, but the type being filtered has no relationship with that name. The resolver validates relationship references inside predicates against the type's declared relationships before using them.

Source

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

    },

    #[error("Invalid operator used in type '{type_name:}' predicate: '{operator_name:}'")]
    InvalidOperatorInTypePredicate {
        type_name: Qualified<CustomTypeName>,
        operator_name: Spanned<OperatorName>,
    },
    #[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>,

View on GitHub (pinned to 724551b9ae)

Solutions

Check `relationship_name` in the message against the relationships declared on `type_name`
Fix the name, or declare the missing relationship on the type
If the relationship was removed intentionally, drop the predicate that uses it

Example fix

# before
relationships:
  - name: authoredPosts
# filter uses {relationship: posts, ...} -> error
# after: use the declared name
{relationship: authoredPosts, ...}

Defensive patterns

Strategy: validation

Validate before calling

// Verify the relationship exists on the type before using it in a predicate
if !object_type.relationships.contains_key(&relationship_name) {
    return Err(format!("relationship {relationship_name} not on type"));
}

Type guard

fn relationship_exists(t: &ObjectType, r: &RelationshipName) -> bool {
    t.relationships.contains_key(r)
}

Try / catch

if let Err(TypePredicateError::UnknownRelationshipInTypePredicate { relationship_name, type_name }) = result {
    return Err(format!("{relationship_name} not declared on {type_name}"));
}

Prevention

Keep filter definitions next to relationship declarations in metadata
Grep for relationship usages when renaming relationships

When it happens

Trigger: Filtering like `{relationship: <name>, ...}` where `<name>` is not declared under the type's relationships; renaming/removing a relationship without updating filters; typo in relationship name.

Common situations: Relationship renames during metadata refactoring; filters written against another model's relationships; namespaced relationship names (qualified names) referenced unqualified.

Related errors

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