antlr/antlr4 · error · IllegalArgumentException

tag cannot be null or empty

Error message

tag cannot be null or empty

What it means

TagChunk is a piece of a parse-tree pattern string (e.g. the ID or expr part of '<ID:identifier>'). Its constructor rejects a null or empty tag because every tag must name a real parser rule or token type for pattern matching to work. This is an IllegalArgumentException thrown eagerly at construction time.

Source

Thrown at runtime/Java/src/org/antlr/v4/runtime/tree/pattern/TagChunk.java:61

	public TagChunk(String tag) {
		this(null, tag);
	}

	/**
	 * Construct a new instance of {@link TagChunk} using the specified label
	 * and tag.
	 *
	 * @param label The label for the tag. If this is {@code null}, the
	 * {@link TagChunk} represents an unlabeled tag.
	 * @param tag The tag, which should be the name of a parser rule or token
	 * type.
	 *
	 * @exception IllegalArgumentException if {@code tag} is {@code null} or
	 * empty.
	 */
	public TagChunk(String label, String tag) {
		if (tag == null || tag.isEmpty()) {
			throw new IllegalArgumentException("tag cannot be null or empty");
		}

		this.label = label;
		this.tag = tag;
	}

	/**
	 * Get the tag for this chunk.
	 *
	 * @return The tag for the chunk.
	 */

	public final String getTag() {
		return tag;
	}

	/**
	 * Get the label, if any, assigned to this chunk.

View on GitHub (pinned to 7d5770395b)

Solutions

1. Check the tag is non-null and non-empty before constructing the TagChunk
2. Prefer parser.compileParseTreePattern(pattern, ruleIndex) over hand-building TagChunk/TextChunk lists
3. Validate dynamically generated pattern strings (each tag between < and > must contain a rule or token name)

Example fix

// before
new TagChunk(label, "");

// after
if (tag == null || tag.isEmpty()) throw new IllegalArgumentException("pattern tag required");
new TagChunk(label, tag);

boolean validTag = tag != null && !tag.isEmpty();

try { new TagChunk(label, tag); } catch (IllegalArgumentException e) { /* report invalid pattern tag: " + tag */ }

When it happens

Trigger: Calling new TagChunk(label, tag) with tag == null or tag.isEmpty(); indirectly via ParseTreePatternBuilder when a pattern chunk is built around an empty tag substring.

Common situations: Building ParseTreePattern strings dynamically (e.g. from config or user input) where a tag token ends up empty, or hand-constructing chunks instead of using parser.compileParseTreePattern.

Related errors

• index cannot be negative
• ANTLR 4 caught {} build errors.
• cannot consume EOF
• missing interface implementation
• Fatal error occured while evaluating the names of the gramma

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