{"record":{"id":"634f8fa336bff466","repo":"Textualize/textual","slug":"syntaxawaredocument-unavailable-tree-sitter-is-n","errorCode":null,"errorMessage":"SyntaxAwareDocument unavailable - tree-sitter is not installed.","messagePattern":"SyntaxAwareDocument unavailable - tree-sitter is not installed\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"src/textual/document/_syntax_aware_document.py","lineNumber":38,"sourceCode":"class SyntaxAwareDocument(Document):\n    \"\"\"A subclass of Document which also maintains a tree-sitter syntax\n    tree when the document is edited.\n    \"\"\"\n\n    def __init__(\n        self,\n        text: str,\n        language: Language,\n    ):\n        \"\"\"Construct a SyntaxAwareDocument.\n\n        Args:\n            text: The initial text contained in the document.\n            language: The tree-sitter language to use.\n        \"\"\"\n\n        if not TREE_SITTER:\n            raise RuntimeError(\n                \"SyntaxAwareDocument unavailable - tree-sitter is not installed.\"\n            )\n\n        super().__init__(text)\n        self.language: Language = language\n        \"\"\"The tree-sitter Language.\"\"\"\n\n        self._parser = Parser(self.language)\n        \"\"\"The tree-sitter Parser or None if tree-sitter is unavailable.\"\"\"\n\n        self._syntax_tree: Tree = self._parser.parse(self._read_callable)  # type: ignore\n        \"\"\"The tree-sitter Tree (syntax tree) built from the document.\"\"\"\n\n    def prepare_query(self, query: str) -> Query | None:\n        \"\"\"Prepare a tree-sitter tree query.\n\n        Queries should be prepared once, then reused.\n","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/Textualize/textual/blob/06dbeef4bb70fb718236aa418ed658ef4667a126/src/textual/document/_syntax_aware_document.py#L20-L56","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the extras: pip install textual[syntax] (or pip install tree-sitter plus the needed tree-sitter-language packages)","Fall back to a plain Document when SyntaxAwareDocument is unavailable","Verify the import in a try/except before opting into syntax-aware mode"],"exampleFix":"# before\ndoc = SyntaxAwareDocument(text, python_language)\n# after\ntry:\n    from textual.document import SyntaxAwareDocument\n    doc = SyntaxAwareDocument(text, python_language)\nexcept (ImportError, RuntimeError):\n    doc = Document(text)","handlingStrategy":"fallback","validationCode":"try:\n    import tree_sitter  # noqa\n    TREE_SITTER_OK = True\nexcept ImportError:\n    TREE_SITTER_OK = False\n\nfrom textual.document import Document\nif not TREE_SITTER_OK:\n    doc = Document(text)  # graceful fallback","typeGuard":"def syntax_support_available() -> bool:\n    try:\n        import tree_sitter  # noqa\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    doc = SyntaxAwareDocument(text, lang)\nexcept RuntimeError as e:\n    if 'tree-sitter' in str(e):\n        doc = Document(text)\n    else:\n        raise","preventionTips":["Install textual[syntax] in environments using SyntaxAwareDocument","Guard the import at startup and fall back to Document","Pin grammar packages for the languages you edit"],"tags":["textual","tree-sitter","optional-dependency","import"],"backgroundTag":"missing-optional-dependency","analyzedSha":"06dbeef4bb70fb718236aa418ed658ef4667a126","analyzedAt":"2026-08-27T02:36:57.214Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}