{"record":{"id":"3b7658616bc6040b","repo":"oraios/serena","slug":"windows-is-not-supported-by-zls-in-this-integratio","errorCode":null,"errorMessage":"Windows is not supported by ZLS in this integration. Cross-file references don't work reliably on Windows. Reason unknown.","messagePattern":"Windows is not supported by ZLS in this integration\\. Cross-file references don't work reliably on Windows\\. Reason unknown\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/solidlsp/language_servers/zls.py","lineNumber":71,"sourceCode":"                return result.stdout.strip()\n        except FileNotFoundError:\n            return None\n        return None\n\n    @staticmethod\n    def _check_zls_installed() -> bool:\n        \"\"\"Check if ZLS is installed in the system.\"\"\"\n        return shutil.which(\"zls\") is not None\n\n    @staticmethod\n    def _setup_runtime_dependency() -> bool:\n        \"\"\"\n        Check if required Zig runtime dependencies are available.\n        Raises RuntimeError with helpful message if dependencies are missing.\n        \"\"\"\n        # Check for Windows and provide error message\n        if platform.system() == \"Windows\":\n            raise RuntimeError(\n                \"Windows is not supported by ZLS in this integration. Cross-file references don't work reliably on Windows. Reason unknown.\"\n            )\n\n        zig_version = ZigLanguageServer._get_zig_version()\n        if not zig_version:\n            raise RuntimeError(\n                \"Zig is not installed. Please install Zig from https://ziglang.org/download/ and make sure it is added to your PATH.\"\n            )\n\n        if not ZigLanguageServer._check_zls_installed():\n            zls_version = ZigLanguageServer._get_zls_version()\n            if not zls_version:\n                raise RuntimeError(\n                    \"Found Zig but ZLS (Zig Language Server) is not installed.\\n\"\n                    \"Please install ZLS from https://github.com/zigtools/zls\\n\"\n                    \"You can install it via:\\n\"\n                    \"  - Package managers (brew install zls, scoop install zls, etc.)\\n\"\n                    \"  - Download pre-built binaries from GitHub releases\\n\"","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/solidlsp/language_servers/zls.py#L53-L89","documentation":"Raised as RuntimeError when a ZLS-backed Zig language server is constructed on Windows. The integration explicitly refuses to run on Windows because cross-file references are unreliable there, so _setup_runtime_dependency hard-fails early with this explanation.","triggerScenarios":"Instantiating the Zig language server (ZigLanguageServer.__init__ → _setup_runtime_dependency) while platform.system() == 'Windows'.","commonSituations":"Developers on Windows or in Windows CI pipelines; WSL confusion where the library runs under Windows Python instead of inside WSL; attempting Windows support before an upstream ZLS fix.","solutions":["Run the code inside WSL (Linux) where ZLS cross-file references work reliably.","Run the code on Linux or macOS instead of Windows.","Use a Docker/Linux container for Zig analysis in CI on Windows runners.","Track ZLS upstream for reliable Windows cross-file reference support before enabling this integration on Windows."],"exampleFix":"// before (Windows PowerShell)\npython -m my_tool analyze-zig\n// after (WSL)\nwsl\n# pip install ... && python -m my_tool analyze-zig","handlingStrategy":"fallback","validationCode":"import platform\nif platform.system() == \"Windows\":\n    raise SystemExit(\"Zig analysis requires Linux/macOS or WSL; run inside WSL instead\")","typeGuard":"def is_zls_supported_platform() -> bool:\n    import platform\n    return platform.system() != \"Windows\"","tryCatchPattern":"try:\n    ls = SolidLSP(\"zig\", repo_path)\nexcept RuntimeError as e:\n    if \"Windows is not supported by ZLS\" in str(e):\n        log.warning(\"Skipping Zig analysis on Windows; rerun under WSL\")\n    else:\n        raise","preventionTips":["Detect platform.system() early and route Windows users to WSL/containers.","In CI on Windows runners, run Zig analysis steps in a Linux container.","Document platform limitations for the Zig integration in your tooling.","Gate Zig-dependent features behind a capability check."],"tags":["platform","windows","zig","unsupported-environment"],"backgroundTag":"unsupported-platform","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}