oraios/serena · error · RuntimeError

Found Zig but ZLS (Zig Language Server) is not installed. Pl

Error message

Found Zig but ZLS (Zig Language Server) is not installed.
Please install ZLS from https://github.com/zigtools/zls
You can install it via:
  - Package managers (brew install zls, scoop install zls, etc.)
  - Download pre-built binaries from GitHub releases
  - Build from source with: zig build -Doptimize=ReleaseSafe

After installation, make sure 'zls' is added to your PATH.

What it means

SolidLSP's ZigLanguageServer requires both the Zig compiler and the ZLS (Zig Language Server) binary. During __init__ it runs _setup_runtime_dependency, which verifies Zig is installed and then checks for ZLS via _check_zls_installed. If Zig exists but the 'zls' executable cannot be found on PATH, a RuntimeError with installation instructions is raised.

Source

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

        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"
                    "  - Build from source with: zig build -Doptimize=ReleaseSafe\n\n"
                    "After installation, make sure 'zls' is added to your PATH."
                )

        return True

    def __init__(self, config: LanguageServerConfig, repository_root_path: str, solidlsp_settings: SolidLSPSettings):
        self._setup_runtime_dependency()

        super().__init__(config, repository_root_path, ProcessLaunchInfo(cmd="zls", cwd=repository_root_path), "zig", solidlsp_settings)
        self.request_id = 0

    def _create_base_initialize_params(self) -> dict:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install ZLS: brew install zls (macOS), scoop install zls (Windows), or download a pre-built binary from https://github.com/zigtools/zls releases
Or build from source: zig clone the zls repo and run `zig build -Doptimize=ReleaseSafe`, then copy zig-out/bin/zls somewhere on PATH
Verify with `which zls` / `zls --version` in the same shell/environment that runs the library
Ensure the ZLS version matches your Zig version (ZLS is version-sensitive)
Re-run the language server initialization

Example fix

// before (shell)
$ zig version
0.13.0
$ which zls
(not found)
// after (shell)
$ brew install zls   # or build: zig build -Doptimize=ReleaseSafe
$ which zls
/usr/local/bin/zls

Defensive patterns

Strategy: validation

Validate before calling

import shutil
if not shutil.which("zls"):
    raise SystemExit("ZLS not found on PATH. Install from https://github.com/zigtools/zls")
if not shutil.which("zig"):
    raise SystemExit("Zig not found on PATH.")

Prevention

Install both zig and zls in your dev container/CI image
Verify with `which zls && zls --version` in the same environment that runs the library
Match ZLS version to your Zig version
Add version-manager shims (mise/asdf) dirs to PATH for the process

When it happens

Trigger: Instantiating the Zig language server (SolidLSP for a .zig repo) when 'zig' resolves on PATH but the 'zls' binary is missing, not executable, or not on PATH.

Common situations: Developers install Zig (e.g. via zigup or a tarball) but forget ZLS; CI containers with zig-only images; ZLS installed via a version manager whose shims aren't on the PATH of the process; ZLS version mismatch causing _get_zls_version to fail.

Related errors

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