hasura/graphql-engine · error · FieldError

Relationship '{name}' is either remote or not having 'relati

Error message

Relationship '{name}' is either remote or not having 'relation_comparisons' NDC capability; not supported for filtering

What it means

FieldError::RelationshipPredicatesNotSupported — a query used relationship predicates (filtering through a relationship, requiring the NDC 'relation_comparisons' capability), but the named relationship is either a remote relationship or its connector lacks that capability, so the filter cannot be pushed down.

Source

Thrown at v3/crates/execute/src/error.rs:44

#[derive(Error, Debug, Transitive)]
#[transitive(from(json::Error, FieldInternalError))]
#[transitive(from(NDCUnexpectedError, FieldInternalError))]
#[transitive(from(gql::normalized_ast::Error, FieldInternalError))]
#[transitive(from(gql::introspection::Error, FieldInternalError))]
#[transitive(from(FilterPredicateError, FieldInternalError))]
pub enum FieldError {
    #[error("error from data source: {}", connector_error.error_response.message())]
    NDCExpected {
        connector_error: ndc_client::ConnectorError,
    },

    #[error("field '{field_name:} not found in _Service")]
    FieldNotFoundInService { field_name: String },

    #[error("subscription are not supported over HTTP")]
    SubscriptionsNotSupported,

    #[error(
        "Relationship '{name}' is either remote or not having 'relation_comparisons' NDC capability; not supported for filtering"
    )]
    RelationshipPredicatesNotSupported { name: RelationshipName },

    #[error("internal error: {0}")]
    InternalError(#[from] FieldInternalError),
}

impl FieldError {
    fn get_details(&self) -> Option<serde_json::Value> {
        match self {
            Self::NDCExpected { connector_error } => {
                Some(connector_error.error_response.details().clone())
            }
            Self::InternalError(internal) => internal.get_details(),
            Self::FieldNotFoundInService { .. }
            | Self::SubscriptionsNotSupported
            | Self::RelationshipPredicatesNotSupported { .. } => None,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rewrite the query to fetch the related entity first and filter client-side, or use two queries
2. If the relationship is local, upgrade the NDC connector to a version supporting relation_comparisons
3. Re-fetch/refresh connector capabilities in metadata after upgrading
4. Model the relationship as local (same connector) if the data can be co-located

Example fix

# before
query { articles(where: {author: {name: {_eq: "Ada"}}}) { id } }

# after
query { authors(where: {name: {_eq: "Ada"}}) { articles { id } } }

null

fn uses_remote_relationship(filter: &Filter) -> bool { /* walk filter tree for relationship predicate targets */ true }

Match FieldError::RelationshipPredicatesNotSupported { name } and either rewrite the query to avoid relationship filtering or surface a clear 'capability not supported for relationship X' error.

When it happens

Trigger: Filtering on a relationship, e.g. query { articles(where: {author: {name: {_eq: "X"}}}) }, where 'author' is a remote relationship or the target connector doesn't advertise relation_comparisons in its capabilities response.

Common situations: Metadata models relationships as remote across services, connector version too old to support relation comparisons, or capability flags not refreshed after connector upgrade.

Related errors

• Type mapping not found for the type name {type_name:} while
• Field mapping not found for the field {field_name:} of type
• setting up global config failed: %w
• error from data source: {}
• {0}

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