hasura/graphql-engine · error · InvalidGraphQlName

{0}

Error message

{0}

What it means

InvalidGraphQlName is thrown when constructing graphql_types::Name from a string that is not a valid GraphQL Name. GraphQL names must match /^[_A-Za-z][_0-9A-Za-z]*$/, and the error's Display is the offending string itself. It guards the boundary where model/field/argument names from metadata enter GraphQL type definitions.

Source

Thrown at v3/crates/graphql/graphql-types/src/lib.rs:8

use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize};
use smol_str::SmolStr;
use std::fmt::{self, Display, Formatter, Write};
use std::str::FromStr;

#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub struct InvalidGraphQlName(pub String);

#[derive(Serialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, JsonSchema)]
pub struct Name(SmolStr);

impl Name {
    pub fn get(&self) -> &SmolStr {
        &self.0
    }
    pub fn take(self) -> SmolStr {
        self.0
    }
    pub fn new(s: &str) -> Result<Name, InvalidGraphQlName> {
        Name::from_str(s)
    }
    pub fn as_str(&self) -> &str {
        self.0.as_str()
    }

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename the entity in metadata to a valid GraphQL name ([_A-Za-z][_0-9A-Za-z]*) — e.g. 'user-id' → 'user_id'
2. Apply the engine's naming conventions/sanitization for data source identifiers so invalid characters are transformed before reaching Name construction
3. Validate names early in metadata ingestion and reject with a clear message naming the offending identifier
4. Add tests for identifier conversion covering hyphens, dots, unicode, and leading digits

Example fix

// before
let name = Name::from_str("order-items")?; // InvalidGraphQlName("order-items")

// after
let name = Name::from_str("order_items")?;

use regex::Regex;
static NAME_RE: Regex = Regex::new(r"^[_A-Za-z][_0-9A-Za-z]*$").unwrap();

fn valid_graphql_name(s: &str) -> bool {
    !s.is_empty() && s.len() <= 256 && NAME_RE.is_match(s)
}

fn is_valid_graphql_name(s: &str) -> bool {
    let mut chars = s.chars();
    matches!(chars.next(), Some(c) if c == '_' || c.is_ascii_alphabetic())
        && chars.all(|c| c == '_' || c.is_ascii_alphanumeric())
}

let name = match Name::from_str(raw_name) {
    Ok(n) => n,
    Err(InvalidGraphQlName(bad)) => {
        return Err(config_error(format!(
            "identifier '{bad}' is not a valid GraphQL name; rename it or apply naming conventions"
        )));
    }
};

When it happens

Trigger: Calling Name::from_str / Name construction (or APIs that build GraphQL schema types from metadata names) with strings containing invalid characters: hyphens, spaces, dots, leading digits, or empty strings. Typical sources are table/column names, relationship names, or header-derived names that never went through GraphQL sanitization.

Common situations: Database tables or columns named like 'user-id', '2023_orders', or 'order.items' surfaced directly as GraphQL names; metadata with unsanitized identifiers; third-party data sources with naming conventions incompatible with GraphQL; failing to apply naming conventions when defining models.

Related errors

• '{name:}' is not a valid GraphQL name.
• '{alias:} is not a valid alias
• error from data source: {}
• subscription are not supported over HTTP
• parsing failed: {0}

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