antlr/antlr4 · error · ArgumentException

${word} at index ${startIndex} isn't a valid token name

Error message

${word} at index ${startIndex} isn't a valid token name

What it means

A word starting with an uppercase character is lexed as a TokenRef, and quoted strings are also treated as token references. Before building the XPath element, the runtime asks the supplied Parser for the token type; TokenConstants.InvalidType means that grammar has no token with that name. Therefore the reference is a syntactically valid token name but is unknown to the target parser.

Source

Thrown at runtime/CSharp/src/Tree/Xpath/XPath.cs:221

            {
                throw new ArgumentException("Missing path element at end of path");
            }
            string word = wordToken.Text;
            int ttype = parser.GetTokenType(word);
            int ruleIndex = parser.GetRuleIndex(word);
            switch (wordToken.Type)
            {
                case XPathLexer.Wildcard:
                {
                    return anywhere ? new XPathWildcardAnywhereElement() : (XPathElement)new XPathWildcardElement();
                }

                case XPathLexer.TokenRef:
                case XPathLexer.String:
                {
                    if (ttype == TokenConstants.InvalidType)
                    {
                        throw new ArgumentException(word + " at index " + wordToken.StartIndex + " isn't a valid token name");
                    }
                    return anywhere ? new XPathTokenAnywhereElement(word, ttype) : (XPathElement)new XPathTokenElement(word, ttype);
                }

                default:
                {
                    if (ruleIndex == -1)
                    {
                        throw new ArgumentException(word + " at index " + wordToken.StartIndex + " isn't a valid rule name");
                    }
                    return anywhere ? new XPathRuleAnywhereElement(word, ruleIndex) : (XPathElement)new XPathRuleElement(word, ruleIndex);
                }
            }
        }

        public static ICollection<IParseTree> FindAll(IParseTree tree, string xpath, Parser parser)
        {
            Antlr4.Runtime.Tree.Xpath.XPath p = new Antlr4.Runtime.Tree.Xpath.XPath(parser, xpath);

View on GitHub (pinned to 7d5770395b)

Solutions

1. Check the generated parser/token vocabulary and correct the token name.
2. If the name is a parser rule, make its first character lowercase so it is treated as a RuleRef.
3. Regenerate the parser from the same grammar version used by the runtime before constructing XPath.
4. Verify parser.GetTokenType(word) does not return TokenConstants.InvalidType before use.

Example fix

// before
var xpath = new Antlr4.Runtime.Tree.Xpath.XPath(parser, "/Ident");

// after
var xpath = new Antlr4.Runtime.Tree.Xpath.XPath(parser, "/ident");
// Or use the actual token name, e.g. "/IDENT".

static bool IsKnownTokenName(Parser parser, string word) {
    return char.IsUpper(word[0]) &&
           parser.GetTokenType(word) != TokenConstants.InvalidType;
}

try { var p = new Antlr4.Runtime.Tree.Xpath.XPath(parser, xpath); }
catch (ArgumentException ex) when (ex.Message.EndsWith("isn't a valid token name")) { /* report unknown token and regenerate parser */ }

When it happens

Trigger: Calling XPath with "/ID" when the grammar defines no ID token; using a token renamed between grammar versions; passing a parser generated from a different grammar; or using an uppercase rule name, which ANTLR interprets as a token reference.

Common situations: Misspelled token names; stale generated parser code after editing a grammar; mixed grammars in one solution; or confusion about the convention that token references start uppercase while rule references start lowercase.

Related errors

• ${word} at index ${startIndex} isn't a valid rule name
• Could not read path: ${path}
• Invalid tokens or characters at index ${pos} in path '${path
• Unknowth path element ${el}
• Missing path element at end of path

AI-assisted analysis of antlr/antlr4@7d5770395b (2026-08-14). Data as JSON: /api/errors/52e50ccfb4a02216. Report an issue: GitHub.