hasura/graphql-engine · error · Error

'{alias:} is not a valid alias

Error message

'{alias:} is not a valid alias

What it means

Field aliases in GraphQL queries must themselves be valid GraphQL names. When the IR parser encounters an alias that fails GraphQL name validation, it throws this error naming the invalid alias. This is distinct from invalid type/field names (error 646) — it specifically covers the 'alias:' portion of a selection.

Source

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

#[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,

    #[error("missing non-nullable argument {argument_name:} for field {field_name:}")]
    MissingNonNullableArgument {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Change the alias to a valid GraphQL name (letters, digits, underscore; not starting with a digit)
2. If aliases are generated, sanitize keys through a name-safe transformation before building the query
3. Lint/validate generated queries before sending them (graphql validation tooling)

Example fix

# before
query {{ user {{ my-alias: name }} }}

# after
query {{ user {{ myAlias: name }} }}

const NAME_RE = /^[_A-Za-z][_0-9A-Za-z]*$/;
function safeAlias(key: string): string {{
  return key.replace(/[^_0-9A-Za-z]/g, '_').replace(/^([0-9])/, '_$1');
}}
if (!NAME_RE.test(alias)) throw new TypeError(`Invalid alias: ${{alias}}`);

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

When it happens

Trigger: A selection like { validField: "bad alias": value } — concretely, any alias containing invalid characters (dashes, spaces, leading digits) or a query built programmatically that interpolates unvalidated strings as aliases.

Common situations: Query builders or GraphQL generators producing aliases from arbitrary keys (e.g. hash strings with dashes, localized labels); templating queries with user text; porting queries from other DSLs.

Related errors

• '{name:}' is not a valid GraphQL name.
• 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/265396ad723e5233. Report an issue: GitHub.