hasura/graphql-engine · error · Error

error in pre-parse plugin: {0}

Error message

error in pre-parse plugin: {0}

What it means

A pre-parse plugin executed as part of subscription processing returned an error before the GraphQL query could be parsed. The graphql-ws pipeline runs registered pre-parse plugins (e.g. query allow-listing, validation) prior to parsing, and any plugin failure aborts with this error.

Source

Thrown at v3/crates/graphql/graphql-ws/src/protocol/subscribe.rs:23

use ::pre_response_plugin::execute::PreResponsePluginResponse;
use axum::http;
use blake2::{Blake2b, Digest};
use engine_types::ExposeInternalErrors;
use graphql_frontend::{ExecuteQueryResult, RootFieldResult, process_response};
use graphql_ir::RequestPlan;
use hasura_authn_core::Session;
use indexmap::IndexMap;
use nonempty::NonEmpty;
use pre_parse_plugin::execute as pre_parse_plugin;
use pre_response_plugin::execute as pre_response_plugin;

#[derive(thiserror::Error, Debug)]
enum Error {
    #[error("graphql-ws protocol is not initialized")]
    NotInitialized,
    #[error("poller with operation_id {} already exists", operation_id.0)]
    PollerAlreadyExists { operation_id: OperationId },
    #[error("error in pre-parse plugin: {0}")]
    PreParsePlugin(#[from] pre_parse_plugin::Error),
}

impl tracing_util::TraceableError for Error {
    fn visibility(&self) -> tracing_util::ErrorVisibility {
        tracing_util::ErrorVisibility::User
    }
}

/// Handles the subscription message from the client.
/// It either starts a new poller or sends a close message if the poller with given operation_id already exists.
pub async fn handle_subscribe<M: WebSocketMetrics>(
    client_address: std::net::SocketAddr,
    connection: ws::Connection<M>,
    operation_id: OperationId,
    payload: lang_graphql::http::RawRequest,
    runtime_flags: metadata_resolve::flags::RuntimeFlags,
) {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Identify which pre-parse plugin rejected the request from server logs (the inner pre_parse_plugin::Error has details)
2. If using an allow-list, add the new query/hash to the plugin's configuration
3. Verify plugin configuration (persisted query manifests, size limits) is deployed alongside the code
4. Test queries against the plugin configuration in CI before deploying

catch (e) { if (String(e).includes('pre-parse plugin')) { surface 'query not allowed' to caller; log inner error; } }

When it happens

Trigger: Registering a pre-parse plugin (query allow-list, persisted-query resolution, size limits) and receiving a subscribe message that the plugin rejects — e.g. a query not on the allow-list or exceeding a configured limit.

Common situations: Deploying a new query not yet added to the allow-list; persisted-query hash unknown to the server; plugin misconfiguration after a version upgrade changes plugin APIs.

Related errors

• error in executing pre-response plugins: {0}
• graphql-ws protocol is not initialized
• poller with operation_id {} already exists
• error in executing pre-response plugins, unable to encode re
• cannot create metadata files: %w

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