Textualize/textual · critical · RuntimeError

SyntaxAwareDocument unavailable - tree-sitter is not install

Error message

SyntaxAwareDocument unavailable - tree-sitter is not installed.

What it means

SyntaxAwareDocument.__init__ raises RuntimeError when the tree-sitter dependency is not importable. The class provides syntax-aware editing (indentation, scope awareness) and requires tree-sitter plus a matching language grammar.

Source

Thrown at src/textual/document/_syntax_aware_document.py:38

class SyntaxAwareDocument(Document):
    """A subclass of Document which also maintains a tree-sitter syntax
    tree when the document is edited.
    """

    def __init__(
        self,
        text: str,
        language: Language,
    ):
        """Construct a SyntaxAwareDocument.

        Args:
            text: The initial text contained in the document.
            language: The tree-sitter language to use.
        """

        if not TREE_SITTER:
            raise RuntimeError(
                "SyntaxAwareDocument unavailable - tree-sitter is not installed."
            )

        super().__init__(text)
        self.language: Language = language
        """The tree-sitter Language."""

        self._parser = Parser(self.language)
        """The tree-sitter Parser or None if tree-sitter is unavailable."""

        self._syntax_tree: Tree = self._parser.parse(self._read_callable)  # type: ignore
        """The tree-sitter Tree (syntax tree) built from the document."""

    def prepare_query(self, query: str) -> Query | None:
        """Prepare a tree-sitter tree query.

        Queries should be prepared once, then reused.

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Install the extras: pip install textual[syntax] (or pip install tree-sitter plus the needed tree-sitter-language packages)
2. Fall back to a plain Document when SyntaxAwareDocument is unavailable
3. Verify the import in a try/except before opting into syntax-aware mode

Example fix

# before
doc = SyntaxAwareDocument(text, python_language)
# after
try:
    from textual.document import SyntaxAwareDocument
    doc = SyntaxAwareDocument(text, python_language)
except (ImportError, RuntimeError):
    doc = Document(text)

try:
    import tree_sitter  # noqa
    TREE_SITTER_OK = True
except ImportError:
    TREE_SITTER_OK = False

from textual.document import Document
if not TREE_SITTER_OK:
    doc = Document(text)  # graceful fallback

def syntax_support_available() -> bool:
    try:
        import tree_sitter  # noqa
        return True
    except ImportError:
        return False

try:
    doc = SyntaxAwareDocument(text, lang)
except RuntimeError as e:
    if 'tree-sitter' in str(e):
        doc = Document(text)
    else:
        raise

When it happens

Trigger: Instantiating SyntaxAwareDocument(text, language) in an environment where the tree_sitter package (and/or the specific language grammar package) is not installed — TREE_SITTER is falsy.

Common situations: Deploying to an environment without the extra: the feature is optional, so 'pip install textual' alone lacks it; CI environments trimming dependencies; grammar package for the chosen language missing.

Related errors

• App {name!r} not found in {lib!r}
• Unable to find app in {lib!r}, try specifying app with "foo.
• Multiple apps found {lib!r}, try specifying app with "foo.py
• Unable to find {find_app!r} in {module!r}
• tree-sitter is available, but no built-in or user-registered

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