hasura/graphql-engine · error · Error

invalid graphql name: {0}

Error message

invalid graphql name: {0}

What it means

A GraphQL name (type, field, argument name) failed validation against the GraphQL name grammar during introspection. GraphQL names must match /[_A-Za-z][_0-9A-Za-z]*/; anything else is rejected when converting to an ast name.

Source

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

// pub mod schema;

use std::collections::HashSet;

use crate::ast::common as ast;
use crate::ast::common::TypeName;
use crate::mk_name;
use crate::normalized_ast as normalized;
use crate::schema;
use crate::schema::RegisteredTypeName;

use indexmap::IndexMap;
use serde_json as json;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("internal introspection error: normalized introspection ast not as expected: {0}")]
    InternalNormalizationError(normalized::Error),
    #[error("invalid graphql name: {0}")]
    InvalidGraphQlName(String),
    #[error("internal introspection error: {0}")]
    Internal(String),
}

impl From<ast::InvalidGraphQlName> for Error {
    fn from(error: ast::InvalidGraphQlName) -> Self {
        Error::InvalidGraphQlName(error.0)
    }
}

impl From<normalized::Error> for Error {
    fn from(error: normalized::Error) -> Self {
        Error::InternalNormalizationError(error)
    }
}

impl From<json::Error> for Error {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename the entity or add an explicit GraphQL-safe name mapping in metadata
2. Sanitize generated names (e.g. camelCase, prefix digits with a letter/underscore)
3. Validate names against the GraphQL grammar before applying metadata

Example fix

# before
type 1album { ... }   # metadata with invalid name
# after
type album1 { ... }

// GraphQL name grammar check before applying metadata
const NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
if (!NAME.test(fieldName)) throw new Error('invalid GraphQL name');

const isValidGraphqlName = (s) => /^[_A-Za-z][_0-9A-Za-z]*$/.test(s);

// Catch, sanitize the offending name, and re-apply metadata

When it happens

Trigger: Metadata defining a type/field whose name starts with a digit or contains invalid characters (spaces, dashes, unicode); database identifiers with illegal characters exposed to GraphQL without sanitization; custom directives/annotations producing invalid names.

Common situations: Tables or columns with hyphens or leading digits mapped directly to GraphQL; hand-written metadata with typo'd names; converting external schemas without name sanitization.

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/2ab8137b4dba7194. Report an issue: GitHub.