{"record":{"id":"e9b7366377990f6b","repo":"hasura/graphql-engine","slug":"remote-joins-are-not-supported-in-subscriptions","errorCode":null,"errorMessage":"remote joins are not supported in subscriptions","messagePattern":"remote joins are not supported in subscriptions","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/crates/graphql/ir/src/plan/error.rs","lineNumber":8,"sourceCode":"use tracing_util::TraceableError;\n\n#[derive(Debug, thiserror::Error)]\npub enum Error {\n    #[error(\"{0}\")]\n    Internal(#[from] InternalError),\n\n    #[error(\"remote joins are not supported in subscriptions\")]\n    RemoteJoinsAreNotSupportedSubscriptions,\n\n    #[error(\"remote predicates are not supported in mutations\")]\n    RemotePredicatesAreNotSupportedInMutations,\n\n    #[error(\"planning returned mutation instead of expected query\")]\n    PlanExpectedQueryGotMutation,\n\n    #[error(\"planning returned query instead of expected mutation\")]\n    PlanExpectedMutationGotQuery,\n\n    #[error(\"{0}\")]\n    OpenDdPlanError(plan::PlanError),\n}\n\nimpl From<plan::PlanError> for Error {\n    fn from(plan_error: plan::PlanError) -> Error {\n        Error::OpenDdPlanError(plan_error)","sourceCodeStart":1,"sourceCodeEnd":26,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/graphql/ir/src/plan/error.rs#L1-L26","documentation":"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.","triggerScenarios":"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.","commonSituations":"Enabling subscriptions on models that have relationships across data sources; expecting federation-style stitching to work in real-time streams.","solutions":["Restructure the subscription to select fields from a single source only","Use the relationship in a query/mutation instead of a subscription","Materialize the remote data locally (e.g. mirror the table) so no join is needed","Check for a newer engine version that adds remote join support in subscriptions"],"exampleFix":"# before\nsubscription { users { posts { title } } }  # posts from remote source\n# after\nsubscription { users { id name } }","handlingStrategy":"fallback","validationCode":"// Inspect the subscription selection: if it spans multiple sources, split or trim it\nconst spansMultipleSources = analyzeSources(subscriptionDoc);\nif (spansMultipleSources) trimToSingleSource();","typeGuard":"const isSingleSource = (doc, sourceMap) =>\n  collectedSourceIds(doc).size <= 1;","tryCatchPattern":"// Catch 'remote joins are not supported in subscriptions' and fall back to a single-source subscription or polling query","preventionTips":["Design subscriptions per source","Materialize cross-source data locally","Document the limitation for API consumers"],"tags":["graphql","subscriptions","remote-joins","planner"],"backgroundTag":"remote-join-unsupported-in-subscription","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}