hasura/graphql-engine · error · Error

unexpected character in the document: {0:?}

Error message

unexpected character in the document: {0:?}

What it means

General lexer error for a character that exists in the GraphQL language but is not valid at the current position while scanning a token, e.g. a stray punctuation mark where a name, number, or string should begin.

Source

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

    }
}

#[derive(Debug)]
pub struct Lexer<'a> {
    bytes: &'a [u8],
    ix: usize,
    line: usize,
    column: usize,
}

/// Error when tokenizing the input source
#[derive(Error, Debug, PartialEq, Eq, Clone)]
pub enum Error {
    /// An unexpected character was found
    ///
    /// Unexpected characters are characters that _do_ exist in the GraphQL
    /// language, but is not expected at the current position in the document.
    #[error("unexpected character in the document: {0:?}")]
    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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the reported position for a misplaced or extra punctuation character
2. Verify template interpolation produced valid GraphQL
3. Re-format/validate the query in a GraphQL editor or linter

Example fix

# before
{ user(id: @1) { name } }   # @ is not valid here
# after
{ user(id: 1) { name } }

let tokens: Result<Vec<_>, _> = lexer::Lexer::new(src).collect(); match tokens { Err(e @ Error::UnexpectedCharacter(c)) => report_position(e), _ => {} }

When it happens

Trigger: Scanning a document where a token starts with or contains unexpected punctuation: '@' in the middle of a name, '#' inside a token (comments must start a token), '}' or ')' where a value is expected mid-lex, etc.

Common situations: Hand-edited queries with misplaced brackets, template placeholders left unfilled, or concatenating fragments incorrectly so punctuation lands mid-token.

Related errors

• unexpected character in string: {0:?}
• invalid number literal found: {0:?}
• parsing failed: {0}
• {0}
• expected a digit, but found: {found:?}

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