oraios/serena · error · RuntimeError

Zig is not installed. Please install Zig from https://ziglan

Error message

Zig is not installed. Please install Zig from https://ziglang.org/download/ and make sure it is added to your PATH.

What it means

Raised as RuntimeError when the Zig compiler cannot be detected: _get_zig_version() returns no version because the zig executable is missing from PATH. ZLS requires a Zig installation to operate, so startup aborts with a pointer to the official download.

Source

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

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

        return True

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install Zig from https://ziglang.org/download/ (or via a package manager: apt, brew, scoop, zigup).
Add the directory containing the zig executable to your PATH.
Verify with `zig version` in the same shell/CI environment that runs the language server.
Point ls_specific_settings.zig/zls at the binaries if PATH cannot be modified.
Fix the broken zig installation if `zig version` errors despite zig being on PATH.

Example fix

// before
# zig: command not found
ls = SolidLSP("zig", "/repo")  # RuntimeError
// after
# export PATH=$PATH:/opt/zig-x86_64-linux-0.13.0
# zig version  # 0.13.0
ls = SolidLSP("zig", "/repo")  # starts

Defensive patterns

Strategy: validation

Validate before calling

import shutil, subprocess
zig = shutil.which("zig")
if not zig:
    raise SystemExit("Zig is not installed; see https://ziglang.org/download/")
subprocess.run([zig, "version"], check=True, capture_output=True)  # binary must actually work

Type guard

def zig_available() -> bool:
    import shutil, subprocess
    z = shutil.which("zig")
    if not z:
        return False
    r = subprocess.run([z, "version"], capture_output=True)
    return r.returncode == 0 and bool(r.stdout.strip())

Try / catch

try:
    ls = SolidLSP("zig", repo_path)
except RuntimeError as e:
    if "Zig is not installed" in str(e):
        subprocess.run(["zigup", "install"], check=True)  # or install via package manager, then retry
        ls = SolidLSP("zig", repo_path)
    else:
        raise

Prevention

Install Zig and add it to PATH in every environment (dev machine, CI image).
Run `zig version` as a preflight check in CI before Zig analysis jobs.
If using version managers (zigup/asdf), ensure they are activated in the executing shell.
Point ls_specific_settings.zig at an explicit zig path when PATH cannot be controlled.

When it happens

Trigger: ZigLanguageServer.__init__ → _setup_runtime_dependency calls ZigLanguageServer._get_zig_version() on a non-Windows platform and gets a falsy result (zig not on PATH or failing to report a version).

Common situations: Zig never installed; zig installed via snapshot/zip download but its directory not added to PATH; version managers (e.g. zigup, asdf) not activated in the shell that runs the server; broken zig binary that exits nonzero.

Related errors

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