What causes ""{name:}" is not a valid GraphQL name." in hasura/graphql-engine?

Rename the offending entity (model/command/argument/type) to match ^[_A-Za-z][_0-9A-Za-z]*$ — the error includes the offending {name}

hasura/graphql-engine · error · GraphqlConfigError

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

Error message

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

What it means

Thrown by the graphql_config resolution stage when a generated or configured GraphQL name fails GraphQL name validation (names must match /[_A-Za-z][_0-9A-Za-z]*/). The resolver validates type names, field names, and argument names it derives from model metadata before building the schema. An invalid name (spaces, leading digits, hyphens, unicode) aborts metadata resolution.

Source

Thrown at v3/crates/metadata-resolve/src/stages/graphql_config/error.rs:47

    )]
    MissingOrderByEnumTypeNamesInGraphqlConfig,
    #[error(
        "only one enumTypeNames can be defined in GraphqlConfig, whose direction values are both 'asc' and 'desc'."
    )]
    MultipleOrderByEnumTypeNamesInGraphqlConfig,
    #[error(
        "invalid directions: {directions} defined in orderByInput of GraphqlConfig , currently there is no support for partial directions. Please specify a type which has both 'asc' and 'desc' directions"
    )]
    InvalidOrderByDirection { directions: String },
    #[error(
        "the fieldName for argumentsInput needs to be defined in GraphqlConfig, when models have argumentsInputType"
    )]
    MissingArgumentsInputFieldInGraphqlConfig,
    #[error(
        "the filterInputFieldName for aggregate needs to be defined in GraphqlConfig, when models have a selectAggregate graphql API"
    )]
    MissingAggregateFilterInputFieldNameInGraphqlConfig,
    #[error("\"{name:}\" is not a valid GraphQL name.")]
    InvalidGraphQlName { name: String },
    #[error("multiple graphql types found with the same name: {graphql_type_name:}")]
    ConflictingGraphQlType { graphql_type_name: ast::TypeName },
}

impl ContextualError for GraphqlConfigError {
    fn create_error_context(&self) -> Option<error_context::Context> {
        None
    }
}

View on GitHub (pinned to 724551b9ae)

Solutions

Rename the offending entity (model/command/argument/type) to match ^[_A-Za-z][_0-9A-Za-z]*$ — the error includes the offending {name}
If the name comes from a database identifier, configure the connector's naming convention or add an explicit alias in the data connector link/metadata
Check the error's span/context to find which metadata object produced the name

Example fix

# before
kind: Model
version: v1
definition:
  name: user-details

# after
kind: Model
version: v1
definition:
  name: userDetails

Defensive patterns

Strategy: validation

Validate before calling

import re
GRAPHQL_NAME = re.compile(r'^[_A-Za-z][_0-9A-Za-z]*$')
assert GRAPHQL_NAME.match(name), f'{name!r} is not a valid GraphQL name'

Prevention

Name metadata entities (models, commands, arguments, types) with GraphQL-safe identifiers from the start
Configure connector naming conventions to sanitize DB identifiers (hyphens/spaces) into camelCase

When it happens

Trigger: Naming a model, command, argument, type, or GraphQL config field with characters invalid in GraphQL (e.g. `2_users`, `user-name`, `user name`), which then flows into a generated GraphQL name during the graphql_config stage.

Common situations: Auto-generating names from database columns or table names containing hyphens/spaces; renaming metadata objects to match DB identifiers; locales/unicode in identifiers.

Related errors

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