hasura/graphql-engine · error · Error

the string {str} in the provided json value is not a valid G

Error message

the string {str} in the provided json value is not a valid GraphQL name

What it means

Thrown when converting a JSON value (e.g. serde_json Value) into GraphQL variables/inputs and a string that must be a valid GraphQL name (`/^[_A-Za-z][_0-9A-Za-z]*$/`) fails that grammar — for example an enum value name or directive/field name coming from untrusted JSON. The error carries the offending string so you can see exactly which name is malformed.

Source

Thrown at v3/crates/graphql/lang-graphql/src/validation/error.rs:73

        alias: ast::Alias,
        field1: ast::Name,
        field2: ast::Name,
    },
    #[error(
        "fields of different type {type1} and {type2} cannot be merged under the same alias: {alias}"
    )]
    FieldsConflictDifferingTypes {
        alias: ast::Alias,
        type1: ast::Type,
        type2: ast::Type,
    },
    #[error("cannot merge fields with different arguments on the same alias: {alias}")]
    FieldsConflictDifferingArguments {
        alias: ast::Alias,
        location1: Option<spanning::SourcePosition>,
        location2: Option<spanning::SourcePosition>,
    },
    #[error("the string {str} in the provided json value is not a valid GraphQL name")]
    NotAValidName { str: String },
    #[error("expected a value of type {expected_type} but found a value of type {actual_type}")]
    IncorrectFormat {
        expected_type: &'static str,
        actual_type: &'static str,
    },
    #[error("a null value found when expected a value of not nullable type: {expected_type}")]
    UnexpectedNull { expected_type: ast::Type },
    #[error("the field {field_name} on type {type_name} is not found")]
    InputFieldNotFound {
        type_name: ast::TypeName,
        field_name: ast::Name,
    },
    #[error("the required fields {} on type {type_name} are not found", field_names.iter().fold(String::new(), |acc, name| acc + &name.to_string()))]
    RequiredInputFieldsNotFound {
        type_name: ast::TypeName,
        field_names: Vec<ast::Name>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Validate/normalize the string to the GraphQL name grammar before conversion: start with a letter or underscore, then letters/digits/underscores only
2. Map kebab-case or spaced backend values to camelCase GraphQL enum names with an explicit conversion table
3. Reject or sanitize untrusted input rather than passing raw JSON strings into name positions

Example fix

// before
let name = json_str; // "in-review"
// after
fn to_graphql_name(s: &str) -> String { s.chars().map(|c| if c.is_alphanumeric() || c == '_' { c } else { '_' }).collect() }

fn is_graphql_name(s: &str) -> bool { let mut c = s.chars(); match c.next() { Some(h) if h == '_' || h.is_ascii_alphabetic() => c.all(|ch| ch == '_' || ch.is_ascii_alphanumeric()), _ => false } }

fn is_graphql_name(s: &str) -> bool { !s.is_empty() && s.bytes().enumerate().all(|(i, b)| b == b'_' || b.is_ascii_alphabetic() || (i > 0 && b.is_ascii_digit())) }

match value_to_input(&json) { Err(Error::NotAValidName { str }) => sanitize_or_reject(&str), r => r }

When it happens

Trigger: Passing JSON-derived enum variant names containing spaces, dashes, or starting with a digit (e.g. "in-review"); constructing dynamic queries/variable values from user input where a name-like string is embedded; deserializing IDs or labels into name positions.

Common situations: Accepting enum values or names from an API/frontend payload and forwarding them into a GraphQL request without sanitization; name grammars differing between systems (kebab-case backend enums vs camelCase GraphQL names); migration scripts feeding legacy identifiers as names.

Related errors

• Unable to parse WebSocket message: {0}
• Unexpected value: expecting {expected_kind:}, but found: {fo
• unable to serialize to json: {0}
• invalid graphql name: {0}
• unable to fetch introspection schema: %w

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