hasura/graphql-engine · error · Error

Only __schema field is expected but found: {name:}

Error message

Only __schema field is expected but found: {name:}

What it means

The introspection handler received a root field other than __schema (name of the offending field is included). Introspection requests are expected to query only the __schema field here, so any other root field is rejected.

Source

Thrown at v3/crates/graphql/lang-graphql/src/generate_graphql_schema.rs:19

/*
This module provides functions to generate introspection result as GraphQL schema
for each namespace from the schema.
 */
use json_ext;
use std::collections::BTreeMap;
use std::sync::OnceLock;
use tracing_util::SpanVisibility;
use tracing_util::{ErrorVisibility, TraceableError};

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("unable to parse introspection query: {0}")]
    ParseIntrospectionQuery(String),
    #[error("unable to normalize introspection query: {0}")]
    NormalizeIntrospectionQuery(String),
    #[error("unable to find field call")]
    FieldCallNotFound,
    #[error("Only __schema field is expected but found: {name:}")]
    OnlySchemaFieldExpected { name: String },
    #[error("introspection query failed: {0}")]
    IntrospactionQueryError(#[from] crate::introspection::Error),
    #[error("unable to serialize to json: {0}")]
    SerializeJson(#[from] serde_json::Error),
}
impl TraceableError for Error {
    fn visibility(&self) -> ErrorVisibility {
        ErrorVisibility::User
    }
}

/// Generate GraphQL schema for a given namespace
pub fn build_namespace_schema<
    S: crate::schema::SchemaContext,
    NSGet: crate::schema::NamespacedGetter<S>,
>(
    namespaced_getter: &NSGet,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Send only the standard __schema-based introspection query to this handler
2. Route regular queries to the normal execution endpoint
3. Use a standard GraphQL client library's introspection query instead of hand-rolling it

Example fix

# before
{ hello }            # sent to introspection handler
# after
{ __schema { types { name } } }

// Route by root field before dispatch
const rootFields = Object.keys(parse(doc).definitions[0].selectionSet.selections.map(s => s.name.value));
if (isIntrospectionHandler && !rootFields.every(f => f === '__schema')) routeToExecution();

const isSchemaOnlyIntrospection = (doc) =>
  rootFieldNames(doc).every(n => n === '__schema');

// Catch and re-route the request to the normal execution endpoint

When it happens

Trigger: Sending a query through the introspection endpoint/handler that selects a root field like __typename or a regular model field instead of __schema; routing ordinary queries into the introspection code path.

Common situations: Custom servers routing all POSTs to the introspection generator; clients probing with mixed queries; tests hitting the wrong handler.

Related errors

• unable to fetch introspection schema: %w
• error in fetching introspection schema: %w
• %s: %d %s
• %s: decoding graphql response errors: %w
• %s: %w

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