oraios/serena · error · FileNotFoundError

shader-language-server is not installed and no auto-install

Error message

shader-language-server is not installed and no auto-install is available for your platform.
Please install it using one of the following methods:
  cargo:   cargo install shader_language_server --locked
  GitHub:  Download from https://github.com/antaalt/shader-sense/releases
On macOS, install the Rust toolchain (https://rustup.rs) and Serena will build from source automatically.
See https://github.com/antaalt/shader-sense for more details.

What it means

The HLSL language server (shader-language-server from shader-sense) is not on the PATH and Serena has no automatic installation method for the current platform, so _get_or_install_core_dependency raises FileNotFoundError with platform-specific install instructions.

Source

Thrown at src/solidlsp/language_servers/hlsl_language_server.py:140

                        platform_id="osx-x64",
                        binary_name="bin/shader-language-server",
                    ),
                    RuntimeDependency(
                        id="shader-language-server",
                        description="shader-language-server for macOS (ARM64) - built from source",
                        command=cargo_install_cmd,
                        platform_id="osx-arm64",
                        binary_name="bin/shader-language-server",
                    ),
                ]
            )

            try:
                dep = deps.get_single_dep_for_current_platform()
            except RuntimeError:
                dep = None

            if dep is None:
                raise FileNotFoundError(
                    "shader-language-server is not installed and no auto-install is available for your platform.\n"
                    "Please install it using one of the following methods:\n"
                    "  cargo:   cargo install shader_language_server --locked\n"
                    "  GitHub:  Download from https://github.com/antaalt/shader-sense/releases\n"
                    "On macOS, install the Rust toolchain (https://rustup.rs) and Serena will build from source automatically.\n"
                    "See https://github.com/antaalt/shader-sense for more details."
                )

            # legacy unversioned dir reserved for INITIAL; every other version goes into a versioned subdir
            ls_dirname = "shader-language-server" if version == _INITIAL_VERSION else f"shader-language-server-{version}"
            install_dir = os.path.join(self._ls_resources_dir, ls_dirname)
            executable_path = deps.binary_path(install_dir)

            if not os.path.exists(executable_path):
                log.info(f"shader-language-server not found. Downloading from {dep.url}")
                _ = deps.install(install_dir)

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install via cargo: `cargo install shader_language_server --locked`, then ensure ~/.cargo/bin is on PATH.
Download a release binary from https://github.com/antaalt/shader-sense/releases and put it on PATH.
On macOS, install the Rust toolchain via https://rustup.rs so Serena can build from source automatically, then retry.
Verify with `which shader-language-server` (or `where` on Windows) that the binary is discoverable before restarting.

Example fix

# before
$ serena start --language hlsl
# FileNotFoundError: shader-language-server is not installed...
# after
$ cargo install shader_language_server --locked
$ export PATH="$HOME/.cargo/bin:$PATH"
$ which shader-language-server
$ serena start --language hlsl

Defensive patterns

Strategy: fallback

Validate before calling

import shutil
def validate_shader_ls_available() -> bool:
    return shutil.which("shader-language-server") is not None
# call before initializing the HLSL language server; if False, install via cargo or GitHub releases first

Try / catch

try:
    ls_path = get_or_install_core_dependency()
except FileNotFoundError as e:
    if "shader-language-server is not installed" in str(e):
        subprocess.run(["cargo", "install", "shader_language_server", "--locked"], check=True)
        os.environ["PATH"] += os.pathsep + os.path.expanduser("~/.cargo/bin")
    else:
        raise

Prevention

Pre-install shader-language-server in your image/Dockerfile (`cargo install shader_language_server --locked`).
Ensure ~/.cargo/bin is on PATH for the process running Serena.
On macOS, install rustup before first use so source builds can succeed.
Check platform support (prebuilt artifacts) before deploying to an unsupported OS/arch.

When it happens

Trigger: _get_or_install_core_dependency calls deps.get_single_dep_for_current_platform(); it throws RuntimeError (no downloadable artifact for this OS/arch) so dep is None, and the code immediately raises FileNotFoundError with the manual-install message.

Common situations: Rust-built shader-language-server not installed on Linux/Windows where no prebuilt binary exists; user never ran `cargo install shader_language_server`; binary built but not in PATH; unsupported platform where only source builds work.

Related errors

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