hasura/graphql-engine · error · Error

remote joins are not supported in subscriptions

Error message

remote joins are not supported in subscriptions

What it means

Raised by the query planner when a subscription plan would require remote joins — fetching related data from a second, remote source to stitch results. The subscription execution path does not support remote joins, so planning aborts.

Source

Thrown at v3/crates/graphql/ir/src/plan/error.rs:8

use tracing_util::TraceableError;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("{0}")]
    Internal(#[from] InternalError),

    #[error("remote joins are not supported in subscriptions")]
    RemoteJoinsAreNotSupportedSubscriptions,

    #[error("remote predicates are not supported in mutations")]
    RemotePredicatesAreNotSupportedInMutations,

    #[error("planning returned mutation instead of expected query")]
    PlanExpectedQueryGotMutation,

    #[error("planning returned query instead of expected mutation")]
    PlanExpectedMutationGotQuery,

    #[error("{0}")]
    OpenDdPlanError(plan::PlanError),
}

impl From<plan::PlanError> for Error {
    fn from(plan_error: plan::PlanError) -> Error {
        Error::OpenDdPlanError(plan_error)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Restructure the subscription to select fields from a single source only
2. Use the relationship in a query/mutation instead of a subscription
3. Materialize the remote data locally (e.g. mirror the table) so no join is needed
4. Check for a newer engine version that adds remote join support in subscriptions

Example fix

# before
subscription { users { posts { title } } }  # posts from remote source
# after
subscription { users { id name } }

// Inspect the subscription selection: if it spans multiple sources, split or trim it
const spansMultipleSources = analyzeSources(subscriptionDoc);
if (spansMultipleSources) trimToSingleSource();

const isSingleSource = (doc, sourceMap) =>
  collectedSourceIds(doc).size <= 1;

// Catch 'remote joins are not supported in subscriptions' and fall back to a single-source subscription or polling query

When it happens

Trigger: Subscribing to a query whose selection set spans multiple sources connected by relationships that require remote joins; subscriptions over federated/relationship data where part of the data lives behind another connector or remote endpoint.

Common situations: Enabling subscriptions on models that have relationships across data sources; expecting federation-style stitching to work in real-time streams.

Related errors

• subscription are not supported over HTTP
• unable to fetch introspection schema: %w
• error in fetching introspection schema: %w
• %s: %d %s
• %s: decoding graphql response errors: %w

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