{"record":{"id":"5e977042b21d25a3","repo":"hasura/graphql-engine","slug":"subscription-are-not-supported-over-http","errorCode":null,"errorMessage":"subscription are not supported over HTTP","messagePattern":"subscription are not supported over HTTP","errorType":"exception","errorClass":"FieldError","httpStatus":null,"severity":"error","filePath":"v3/crates/execute/src/error.rs","lineNumber":41,"sourceCode":"/// Field errors are raised during execution from a root field\n/// Ref: <https://spec.graphql.org/October2021/#sec-Errors.Field-errors>\n#[allow(clippy::duplicated_attributes)] // suppress spurious warnings from Clippy\n#[derive(Error, Debug, Transitive)]\n#[transitive(from(json::Error, FieldInternalError))]\n#[transitive(from(NDCUnexpectedError, FieldInternalError))]\n#[transitive(from(gql::normalized_ast::Error, FieldInternalError))]\n#[transitive(from(gql::introspection::Error, FieldInternalError))]\n#[transitive(from(FilterPredicateError, FieldInternalError))]\npub enum FieldError {\n    #[error(\"error from data source: {}\", connector_error.error_response.message())]\n    NDCExpected {\n        connector_error: ndc_client::ConnectorError,\n    },\n\n    #[error(\"field '{field_name:} not found in _Service\")]\n    FieldNotFoundInService { field_name: String },\n\n    #[error(\"subscription are not supported over HTTP\")]\n    SubscriptionsNotSupported,\n\n    #[error(\n        \"Relationship '{name}' is either remote or not having 'relation_comparisons' NDC capability; not supported for filtering\"\n    )]\n    RelationshipPredicatesNotSupported { name: RelationshipName },\n\n    #[error(\"internal error: {0}\")]\n    InternalError(#[from] FieldInternalError),\n}\n\nimpl FieldError {\n    fn get_details(&self) -> Option<serde_json::Value> {\n        match self {\n            Self::NDCExpected { connector_error } => {\n                Some(connector_error.error_response.details().clone())\n            }\n            Self::InternalError(internal) => internal.get_details(),","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/execute/src/error.rs#L23-L59","documentation":"FieldError::SubscriptionsNotSupported — a GraphQL subscription operation was sent over the plain HTTP transport, which this engine only handles for queries and mutations. The error is deterministic: the HTTP execution path explicitly rejects subscription operations.","triggerScenarios":"Sending a subscription document (operation type 'subscription') to the engine's HTTP endpoint, e.g. POST /graphql with a subscription query, instead of opening a WebSocket connection.","commonSituations":"Clients or tools defaulting to HTTP for all operation types, missing WebSocket configuration in the GraphQL client, or test scripts POSTing subscription queries.","solutions":["Use the WebSocket (graphql-ws/subscription-transport-ws) endpoint for subscriptions","Change the operation to a query/mutation if realtime behavior isn't needed","Configure your GraphQL client (urql/apollo-relay etc.) to route subscriptions to the WS URL"],"exampleFix":"# before\nPOST /graphql  { \"query\": \"subscription { userAdded { id } }\" }\n\n# after\n# connect via websocket\nnew GraphQLWsLink(new WebSocketClient('wss://host/graphql'))","handlingStrategy":"validation","validationCode":"import { parse } from 'graphql';\nconst opType = parse(query).definitions[0].operation;\nif (opType === 'subscription') throw new Error('use the WebSocket endpoint for subscriptions');","typeGuard":"fn is_subscription(doc: &graphql::Request) -> bool { /* inspect parsed operation type */ true }","tryCatchPattern":"Match FieldError::SubscriptionsNotSupported and return an HTTP 400 with a message directing the client to the WebSocket endpoint.","preventionTips":["Configure GraphQL clients with a WS link for subscriptions","Reject subscription documents at the gateway HTTP layer early","Document transport requirements for each operation type"],"tags":["graphql","subscriptions","http","websocket","rust"],"backgroundTag":"subscriptions-over-http-unsupported","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}