hasura/graphql-engine · error · Error

'{name:}' is not a valid GraphQL name.

Error message

'{name:}' is not a valid GraphQL name.

What it means

The IR layer validates that entity/type/field names used in queries or configuration conform to the GraphQL name grammar (^[_A-Za-z][_0-9A-Za-z]*$). When a name contains invalid characters (spaces, dashes, leading digits, etc.) this error names the offending name. It guards against injection of malformed identifiers deeper into planning and SQL generation.

Source

Thrown at v3/crates/graphql/ir/src/error.rs:52

#[derive(Error, Debug, Transitive)]
#[transitive(from(json::Error, InternalError))]
#[transitive(from(gql::normalized_ast::Error, InternalError))]
#[transitive(from(InternalEngineError, InternalError))]
#[transitive(from(InternalDeveloperError, InternalError))]
pub enum Error {
    #[error("The global ID {encoded_value:} couldn't be decoded due to {decoding_error:}")]
    FailureDecodingGlobalId {
        encoded_value: String,
        decoding_error: String,
    },

    #[error("Unexpected value: expecting {expected_kind:}, but found: {found:}")]
    UnexpectedValue {
        expected_kind: &'static str,
        found: json::Value,
    },

    #[error("'{name:}' is not a valid GraphQL name.")]
    TypeFieldInvalidGraphQlName { name: String },

    #[error("'{alias:} is not a valid alias")]
    InvalidAlias { alias: String },

    #[error("{value} is not a valid limit value")]
    InvalidLimitValue { value: u32 },

    #[error("{value} is not a valid offset value")]
    InvalidOffsetValue { value: u32 },

    #[error("field '{field_name:} not found in entity representation")]
    FieldNotFoundInEntityRepresentation { field_name: FieldName },

    #[error(
        "order_by expects a list of input objects with exactly one key-value pair per input object. Please split the input object with multiple key-value pairs into a list of single key-value pair objects."
    )]
    OrderByObjectShouldExactlyHaveOneKeyValuePair,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename the field/type to a valid GraphQL identifier (camelCase or snake_case, letter or underscore first)
2. If mapping from external names, apply a sanitization/aliasing step before constructing the query
3. Add a regex check for ^[_A-Za-z][_0-9A-Za-z]*$ before using client-supplied names

Example fix

# before
query {{ user {{ my-field }} }}

# after
query {{ user {{ myField }} }}

const NAME_RE = /^[_A-Za-z][_0-9A-Za-z]*$/;
if (!NAME_RE.test(fieldName)) throw new TypeError(`Invalid GraphQL name: ${{fieldName}}`);

function isValidGraphqlName(name: string): boolean {{
  return /^[_A-Za-z][_0-9A-Za-z]*$/.test(name);
}}

When it happens

Trigger: A query or configuration uses a type or field name with characters outside the GraphQL name grammar — e.g. 'my-field', '2users', 'user name' — reaching the IR name validation path.

Common situations: Dynamically building queries from user input; configuration files mapping database column names with dashes directly to GraphQL field names; codegen producing names that weren't sanitized.

Related errors

• '{alias:} is not a valid alias
• validation failed: {0}
• {0}
• Unexpected value: expecting {expected_kind:}, but found: {fo
• {value} is not a valid limit value

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