oraios/serena · error · RuntimeError

Windows is not supported by ZLS in this integration. Cross-f

Error message

Windows is not supported by ZLS in this integration. Cross-file references don't work reliably on Windows. Reason unknown.

What it means

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.

Source

Thrown at src/solidlsp/language_servers/zls.py:71

                return result.stdout.strip()
        except FileNotFoundError:
            return None
        return None

    @staticmethod
    def _check_zls_installed() -> bool:
        """Check if ZLS is installed in the system."""
        return shutil.which("zls") is not None

    @staticmethod
    def _setup_runtime_dependency() -> bool:
        """
        Check if required Zig runtime dependencies are available.
        Raises RuntimeError with helpful message if dependencies are missing.
        """
        # Check for Windows and provide error message
        if platform.system() == "Windows":
            raise RuntimeError(
                "Windows is not supported by ZLS in this integration. Cross-file references don't work reliably on Windows. Reason unknown."
            )

        zig_version = ZigLanguageServer._get_zig_version()
        if not zig_version:
            raise RuntimeError(
                "Zig is not installed. Please install Zig from https://ziglang.org/download/ and make sure it is added to your PATH."
            )

        if not ZigLanguageServer._check_zls_installed():
            zls_version = ZigLanguageServer._get_zls_version()
            if not zls_version:
                raise RuntimeError(
                    "Found Zig but ZLS (Zig Language Server) is not installed.\n"
                    "Please install ZLS from https://github.com/zigtools/zls\n"
                    "You can install it via:\n"
                    "  - Package managers (brew install zls, scoop install zls, etc.)\n"
                    "  - Download pre-built binaries from GitHub releases\n"

View on GitHub (pinned to 7fcbca7e62)

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.

Example fix

// before (Windows PowerShell)
python -m my_tool analyze-zig
// after (WSL)
wsl
# pip install ... && python -m my_tool analyze-zig

Defensive patterns

Strategy: fallback

Validate before calling

import platform
if platform.system() == "Windows":
    raise SystemExit("Zig analysis requires Linux/macOS or WSL; run inside WSL instead")

Type guard

def is_zls_supported_platform() -> bool:
    import platform
    return platform.system() != "Windows"

Try / catch

try:
    ls = SolidLSP("zig", repo_path)
except RuntimeError as e:
    if "Windows is not supported by ZLS" in str(e):
        log.warning("Skipping Zig analysis on Windows; rerun under WSL")
    else:
        raise

Prevention

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.

When it happens

Trigger: Instantiating the Zig language server (ZigLanguageServer.__init__ → _setup_runtime_dependency) while platform.system() == 'Windows'.

Common situations: 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.

Related errors

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/3b7658616bc6040b. Report an issue: GitHub.