oraios/serena · error · FileNotFoundError

shader-language-server not found at {executable_path}

Error message

shader-language-server not found at {executable_path}

What it means

After attempting to install shader-language-server from a downloaded dep artifact, the expected executable still does not exist at executable_path, so _get_or_install_core_dependency raises FileNotFoundError. It means the install step (deps.install) completed but the binary did not land where expected.

Source

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

                    "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)

            if not os.path.exists(executable_path):
                raise FileNotFoundError(f"shader-language-server not found at {executable_path}")

            os.chmod(executable_path, 0o755)
            return executable_path

        def _create_launch_command(self, core_path: str) -> list[str]:
            return [core_path, "--stdio"]

    def _create_base_initialize_params(self) -> dict:
        initialize_params = {
            "locale": "en",
            "capabilities": {
                "textDocument": {
                    "synchronization": {"didSave": True, "dynamicRegistration": True},
                    "completion": {
                        "dynamicRegistration": True,
                        "completionItem": {"snippetSupport": True},
                    },
                    "definition": {"dynamicRegistration": True},

View on GitHub (pinned to 7fcbca7e62)

Solutions

Check install_dir for the binary — it may exist under a different name or nested path; move/symlink it to executable_path.
Manually download from dep.url / the shader-sense releases page and place the binary at the expected path.
Retry deps.install after clearing the install dir (partial/corrupt extraction).
Verify the expected executable name matches the platform (e.g. shader-language-server.exe on Windows) and update the path resolution if needed.

Example fix

# before
if not os.path.exists(executable_path):
    raise FileNotFoundError(f"shader-language-server not found at {executable_path}")
# after (manual fallback placement)
# mv ~/.cache/serena/shader-sense/bin/shader-language-server <expected_path>
# chmod +x <expected_path>

Defensive patterns

Strategy: validation

Validate before calling

import os
def validate_shader_ls_path(expected_path: str) -> bool:
    return os.path.isfile(expected_path) and os.access(expected_path, os.X_OK)
# also inspect install_dir for binaries under alternate names before raising

Try / catch

try:
    ls_path = get_or_install_core_dependency()
except FileNotFoundError as e:
    if "not found at" in str(e):
        candidate = find_binary(install_dir, "shader-language-server")
        if candidate:
            os.chmod(candidate, 0o755)
            os.symlink(candidate, expected_path)
        else:
            manual_install_from_releases()
    else:
        raise

Prevention

After install failures, list install_dir contents to spot renamed/nested binaries.
Pin the dep.url to a stable release asset that will not 404.
Confirm the expected filename per platform (.exe on Windows).
Clear and reinstall the install dir when a download was interrupted.

When it happens

Trigger: _get_or_install_core_dependency: first os.path.exists(executable_path) fails, deps.install(install_dir) runs (downloading from dep.url), but the second os.path.exists(executable_path) check still fails, raising the error before os.chmod.

Common situations: Download failed silently or URL changed (dep.url 404s / release renamed assets); archive extraction placed the binary under a different directory or with a versioned filename; the installed binary name differs from the expected `shader-language-server` (e.g. .exe suffix on Windows); disk full during install.

Related errors

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