Textualize/textual · error · ValueError

Index {index!r} does not correspond to a location in the doc

Error message

Index {index!r} does not correspond to a location in the document.

What it means

Document.get_location_from_index raises ValueError when the given string index is negative or beyond len(document.text). The index space is character offsets into the whole document text.

Source

Thrown at src/textual/document/_document.py:388

        return index

    def get_location_from_index(self, index: int) -> Location:
        """Given a codepoint index in the document's text, returns the corresponding location.

        Args:
            index: The index in the document's text.

        Returns:
            The corresponding location.

        Raises:
            ValueError: If the index is doesn't correspond to a location in the document.
        """
        error_message = (
            f"Index {index!r} does not correspond to a location in the document."
        )
        if index < 0 or index > len(self.text):
            raise ValueError(error_message)

        column_index = 0
        newline_length = len(self.newline)
        for line_index in range(self.line_count):
            next_column_index = (
                column_index + len(self.get_line(line_index)) + newline_length
            )
            if index < next_column_index:
                return (line_index, index - column_index)
            elif index == next_column_index:
                return (line_index + 1, 0)
            column_index = next_column_index

        raise ValueError(error_message)

    def get_line(self, index: int) -> str:
        """Returns the line with the given index from the document.

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Clamp the index: max(0, min(index, len(document.text)))
2. Recompute indices from document.text length rather than external counters
3. For unicode, use character-based indices, not byte offsets

Example fix

# before
loc = doc.get_location_from_index(index + len(inserted))
# after
loc = doc.get_location_from_index(min(index + len(inserted), len(doc.text)))

def clamped(doc, index: int) -> int:
    return max(0, min(index, len(doc.text)))

def valid_index(doc, index: int) -> bool:
    return 0 <= index <= len(doc.text)

try:
    loc = doc.get_location_from_index(index)
except ValueError:
    loc = (doc.line_count - 1, len(doc.get_line(doc.line_count - 1)))

When it happens

Trigger: Calling get_location_from_index(-1) or with an index past the end (e.g. len(text) + 1), often from arithmetic like index + offset that overruns.

Common situations: Cursor/selection computations in TextArea-derived widgets that add or subtract offsets without clamping; using byte lengths instead of character counts for unicode text.

Related errors

• The document line index {line_index!r} is out of bounds. The
• Cannot add an edit to history before it has been performed u
• Can't animate attribute {attribute!r} on {obj!r}; attribute
• Don't know how to animate {value!r}; Can only animate <int>,
• Can't encode {datum!r}

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/384d05dd4efe6f5d. Report an issue: GitHub.