antlr/antlr4 · error · NotSupportedException

seek to index outside buffer: ${index} not in ${bufferStartI

Error message

seek to index outside buffer: ${index} not in ${bufferStartIndex}..${bufferStartIndex+n}

What it means

Seek() first tries to synchronize the requested position into the rolling buffer. If the requested absolute index still maps beyond the end of that buffer, the stream cannot provide that position and throws NotSupportedException. This is distinct from the negative-index case, which indicates discarded data behind the stream.

Source

Thrown at runtime/CSharp/src/UnbufferedCharStream.cs:391

            {
                return;
            }
            if (index > currentCharIndex)
            {
                Sync(index - currentCharIndex);
                index = Math.Min(index, BufferStartIndex + n - 1);
            }
            // index == to bufferStartIndex should set p to 0
            int i = index - BufferStartIndex;
            if (i < 0)
            {
                throw new ArgumentException("cannot seek to negative index " + index);
            }
            else
            {
                if (i >= n)
                {
                    throw new NotSupportedException("seek to index outside buffer: " + index + " not in " + BufferStartIndex + ".." + (BufferStartIndex + n));
                }
            }
            p = i;
            currentCharIndex = index;
            if (p == 0)
            {
                lastChar = lastCharBufferStart;
            }
            else
            {
                lastChar = data[p - 1];
            }
        }

        public virtual int Size
        {
            get
            {

View on GitHub (pinned to 7d5770395b)

Solutions

1. Avoid long forward seeks; consume or Sync incrementally instead.
2. Check index calculations against the actual stream position before seeking.
3. Use AntlrInputStream when jump-to-index access is required.

Example fix

// before
chars.Seek(targetIndex); // target may not be synchronizable

// after
if (targetIndex > chars.Index)
    while (chars.Index < targetIndex && chars.LA(1) != IntStreamConstants.EOF)
        chars.Consume();
chars.Seek(Math.Min(targetIndex, chars.Index));

if (targetIndex > chars.Index) {
    while (chars.Index < targetIndex && chars.LA(1) != IntStreamConstants.EOF)
        chars.Consume();
}
chars.Seek(Math.Min(targetIndex, chars.Index));

try { chars.Seek(index); }
catch (NotSupportedException ex) when (ex.Message.StartsWith("seek to index outside buffer")) { /* consume incrementally or use AntlrInputStream */ }

When it happens

Trigger: Calling Seek() with an index far ahead of what has been read; seeking to an index beyond available input/EOF under buffering constraints; or custom code assuming the unbuffered stream can jump arbitrarily far forward.

Common situations: Absolute-index navigation from buffered token-stream code is reused on UnbufferedCharStream; incorrect char-index arithmetic after multi-byte/surrogate handling; or attempts to seek to a computed EOF position.

Related errors

• cannot seek to negative index ${index}
• cannot consume EOF
• release() called with an invalid marker.
• Unbuffered stream cannot know its size
• interval ${interval} outside buffer: ${bufferStartIndex}..${

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