hasura/graphql-engine · error · Error

invalid graphql name: {0}

Error message

invalid graphql name: {0}

What it means

Thrown when a name token does not conform to GraphQL's name grammar (/_A-Za-z][_0-9A-Za-z]*/), such as a name starting with a digit or containing '-'. It can also be produced by converting ast::common::InvalidGraphQlName (names generated programmatically, e.g. from field names, that violate the grammar).

Source

Thrown at v3/crates/graphql/lang-graphql/src/lexer.rs:159

    UnexpectedCharacter(char),

    /// The input source was unexpectedly terminated
    ///
    /// Emitted when the current token requires a succeeding character, but
    /// the source has reached EOF. Emitted when scanning e.g. `"1."`.
    #[error("end of file reached when expecting further input")]
    UnexpectedEndOfFile,

    /// An invalid string literal was found
    #[error("invalid string literal found: {0:?}")]
    InvalidString(string::Error),

    /// An invalid number literal was found
    #[error("invalid number literal found: {0:?}")]
    InvalidNumber(number::Error),

    // An invalid graphql name
    #[error("invalid graphql name: {0}")]
    InvalidGraphQlName(String),
}

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

pub type Result = core::result::Result<Spanning<Token>, Positioned<Error>>;

#[inline]
fn consume_ascii_chars<F>(data: &[u8], mut f: F) -> usize
where
    F: FnMut(u8) -> bool,
{
    data.iter().take_while(|&&c| f(c)).count()
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename the field to valid GraphQL name syntax (letters, digits, _, no leading digit)
2. Add a mapping/alias layer converting external names to sanitized GraphQL names
3. If from codegen, configure the generator to sanitize identifiers

Example fix

# before
type User { user-name: String }
# after
type User { userName: String }

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

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

Catch Error::InvalidGraphQlName(name) during lexing/AST construction and apply a sanitize_name fallback before retrying.

When it happens

Trigger: Lexing a document where a name starts with a digit or contains invalid characters ('my-field', '2fast'), or building AST nodes/deriving GraphQL names from external identifiers (DB column names with dashes/spaces) that fail name validation.

Common situations: Exposing database columns or JSON keys with hyphens/spaces as GraphQL field or type names; codegen from OpenAPI/protobuf that produces non-identifier names.

Related errors

• expected a digit, but found: {found:?}
• failed to parse a number: {error:?}
• lookahead of a number cannot be a 'NameStart': {0:?}
• expected a \" but found: {0:?}
• string is unterminated

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