hasura/graphql-engine · error · GraphQlParseError

{0}

Error message

{0}

What it means

GraphQlParseError is a thin newtype over the gql parser error (with source position) raised when parsing a GraphQL document fails in contexts where a standalone TraceableError is required. Its Display is transparent ('{0}'), so the message shown is the parser's own diagnostic. It is marked User-visible, meaning it is safe to return to API clients.

Source

Thrown at v3/crates/graphql/frontend/src/types.rs:84

        }
    }

    pub fn inner(self) -> gql::http::Response {
        self.0
    }
}

/// Implement traceable for GraphQL Response
impl Traceable for GraphQLResponse {
    type ErrorType<'a> = GraphQLErrors<'a>;

    fn get_error(&self) -> Option<GraphQLErrors<'_>> {
        self.0.errors.as_ref().map(GraphQLErrors)
    }
}

#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub struct GraphQlParseError(#[from] pub gql::ast::spanning::Positioned<gql::parser::Error>);

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

#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub struct GraphQlValidationError(#[from] pub gql::validation::Error);
impl TraceableError for GraphQlValidationError {
    fn visibility(&self) -> ErrorVisibility {
        ErrorVisibility::User
    }
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the wrapped gql::parser::Error position to find the offending token and fix the document
2. Sanitize/validate GraphQL text at ingestion time rather than when re-parsing later
3. Add round-trip tests (parse → print → parse) for generated or stored documents
4. Check for encoding issues (UTF-8 BOM, non-breaking spaces) if the text looks valid

Example fix

// before
let doc = gql::parser::parse_schema(&raw)?;

// after
match graphql_frontend::types::GraphQlParseError::from_parser(&raw) {
    Ok(doc) => doc,
    Err(e) => { return Err(bad_request(format!("invalid GraphQL: {e}"))); }
}

// Validate stored documents at write time, not read time:
fn store_query(raw: &str) -> Result<(), String> {
    gql_parse_check(raw).map_err(|e| format!("invalid GraphQL: {e} at {}", e.pos))?;
    db.insert(raw);
    Ok(())
}

fn is_parse_error(e: &dyn std::error::Error) -> bool {
    e.downcast_ref::<graphql_frontend::types::GraphQlParseError>().is_some()
}

use graphql_frontend::types::GraphQlParseError;
match parse_document(raw) {
    Ok(doc) => doc,
    Err(e) => {
        let e = GraphQlParseError::from(e); // TraceableError, User-visible
        return Err(UserVisible(e.to_string()));
    }
}

When it happens

Trigger: Any code path that constructs GraphQlParseError — typically parsing stored/incoming GraphQL documents (e.g. persisted queries, schema documents, websocket message payloads) where the text is not valid GraphQL syntax.

Common situations: Corrupted or truncated persisted query strings; user-supplied GraphQL text stored in a database later re-parsed; whitespace/encoding issues (BOM, CRLF) in query files; queries written against a different GraphQL dialect.

Related errors

• parsing failed: {0}
• error from data source: {}
• subscription are not supported over HTTP
• validation failed: {0}
• explain error: {0}

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