What causes "parsing failed: {0}" in hasura/graphql-engine?

Fix the GraphQL syntax error indicated by the wrapped parser error and its position

hasura/graphql-engine · error · RequestError::ParseFailure

parsing failed: {0}

Error message

parsing failed: {0}

What it means

RequestError::ParseFailure is raised by the GraphQL frontend when the incoming GraphQL query string cannot be parsed into an AST. It transparently wraps the underlying gql parser error (including its source position), so the message is 'parsing failed: {0}' with the parser's own diagnostic appended. This is a request error per the GraphQL spec: it occurs before any root field execution begins.

Source

Thrown at v3/crates/graphql/frontend/src/error.rs:11

use axum::response::IntoResponse;
use engine_types::ExposeInternalErrors;
use gql::http::GraphQLError;
use lang_graphql as gql;
use tracing_util::{ErrorVisibility, TraceableError};

/// Request errors are raised before execution of root fields begins.
/// Ref: <https://spec.graphql.org/October2021/#sec-Errors.Request-errors>
#[derive(Debug, thiserror::Error)]
pub enum RequestError {
    #[error("parsing failed: {0}")]
    ParseFailure(#[from] gql::ast::spanning::Positioned<gql::parser::Error>),

    #[error("validation failed: {0}")]
    ValidationFailed(#[from] gql::validation::Error),

    #[error("{0}")]
    IRConversionError(#[from] graphql_ir::Error),

    #[error("{0}")]
    GraphQlPlanError(#[from] graphql_ir::GraphqlIrPlanError),

    #[error("explain error: {0}")]
    ExplainError(String),
}

impl RequestError {
    pub fn to_graphql_error(&self, expose_internal_errors: ExposeInternalErrors) -> GraphQLError {
        let message = match (self, expose_internal_errors) {

View on GitHub (pinned to 724551b9ae)

Solutions

Fix the GraphQL syntax error indicated by the wrapped parser error and its position
Paste the query into a GraphQL IDE/linter (GraphiQL, graphql-inspector) to locate the syntax problem
If generating queries programmatically, validate generated strings against the schema in tests
Ensure the query field in the JSON request body is the raw GraphQL document, not double-encoded

Example fix

// before
query { user(id: 1 { name }

// after
query { user(id: 1) { name } }

Defensive patterns

Strategy: validation

Validate before calling

// Validate document syntax before sending to the server:
// (js) use graphql-js `parse` client-side
import { parse } from 'graphql';
function safeQuery(q) {
  try { parse(q); return q; } catch (e) { throw new Error(`Invalid GraphQL syntax: ${e.message}`); }
}

Try / catch

match graphql_frontend::execute_request(&req).await {
    Err(e) if matches!(e, RequestError::ParseFailure(_)) => {
        // 400 Bad Request with the parser diagnostic (includes position)
        bad_request(e.to_string())
    }
    rest => rest,
}

Prevention

Lint queries in CI with graphql-inspector or similar before deploy
Use typed codegen clients so hand-written syntax errors never reach production
Return 400 (not 500) for parse failures since they are client errors

When it happens

Trigger: Sending a malformed GraphQL document to the GraphQL API: unbalanced braces/brackets, missing selection set, invalid tokens, bad syntax in argument literals, or a stray keyword. Produced during request parsing in graphql/frontend before validation or IR conversion.

Common situations: Typos in hand-written queries; clients concatenating query fragments incorrectly; sending a JSON-encoded query with escaped characters mangled; automated tooling generating invalid GraphQL; sending a mutation keyword where the parser expects a query.

Related errors

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