oraios/serena · error · FileNotFoundError

Clangd executable not found at {clangd_executable_path}. Mak

Error message

Clangd executable not found at {clangd_executable_path}.
Make sure you have installed clangd. See https://clangd.llvm.org/installation

What it means

_get_or_install_core_dependency raises FileNotFoundError when the expected clangd executable still does not exist at clangd_executable_path even after deps.install downloaded and extracted the prebuilt binary. This means the managed install did not produce the binary at the expected location (deps.binary_path), typically due to a changed archive layout or failed extraction.

Source

Thrown at src/solidlsp/language_servers/clangd_language_server.py:304

                clangd_executable_path = shutil.which("clangd")
                if not clangd_executable_path:
                    raise FileNotFoundError(
                        "Clangd is not installed on your system.\n"
                        + "Please install clangd using your system package manager:\n"
                        + "  Ubuntu/Debian: sudo apt-get install clangd\n"
                        + "  Fedora/RHEL: sudo dnf install clang-tools-extra\n"
                        + "  Arch Linux: sudo pacman -S clang\n"
                        + "See https://clangd.llvm.org/installation for more details."
                    )
                log.info(f"Using system-installed clangd at {clangd_executable_path}")
            else:
                # Standard download and install for platforms with prebuilt binaries
                clangd_executable_path = deps.binary_path(clangd_ls_dir)
                if not os.path.exists(clangd_executable_path):
                    log.info(f"Clangd executable not found at {clangd_executable_path}. Downloading from {dep.url}")
                    _ = deps.install(clangd_ls_dir)
                if not os.path.exists(clangd_executable_path):
                    raise FileNotFoundError(
                        f"Clangd executable not found at {clangd_executable_path}.\n"
                        + "Make sure you have installed clangd. See https://clangd.llvm.org/installation"
                    )
                os.chmod(clangd_executable_path, 0o755)
            return clangd_executable_path

        def _create_launch_command(self, core_path: str) -> list[str]:
            # --background-index enables clangd to index all files in the project,
            # which is required for finding cross-file references
            return [core_path, "--background-index"]

    def _create_base_initialize_params(self) -> dict:
        """
        Returns the initialize params for the clangd Language Server.
        """
        initialize_params = {
            "locale": "en",
            "capabilities": {

View on GitHub (pinned to 7fcbca7e62)

Solutions

Delete the managed clangd install directory (clangd_ls_dir) to force a clean download/re-extract and retry
Inspect the install directory to find where the binary was actually extracted and check the archive layout
Manually install clangd system-wide (apt/dnf/pacman per the related error) so the system-installed path is used
Update to a library version matching the current upstream clangd release layout

Example fix

// before
# managed install fails to produce binary -> FileNotFoundError
rm -rf ~/.cache/serena/language_servers/clangd*
// after
# restart server; clean managed install succeeds
clangd --version

Defensive patterns

Strategy: retry

Validate before calling

import os
expected = deps_binary_path(clangd_ls_dir)  # same path the library computes
if not os.path.exists(expected):
    print("clangd binary missing in managed dir; clear it to force re-download")

Try / catch

try:
    server = ClangdLanguageServer(...)
except FileNotFoundError as e:
    if "executable not found at" in str(e):
        shutil.rmtree(clangd_ls_dir, ignore_errors=True)
        server = ClangdLanguageServer(...)  # clean managed reinstall
    else:
        raise

Prevention

Clear the managed clangd install directory after failed installs or library upgrades
Ensure sufficient disk space and write permissions in the resources/cache directory
Prefer a system-installed clangd when upstream archive layouts change

When it happens

Trigger: Platform uses the standard prebuilt download path; deps.install(clangd_ls_dir) runs without raising, but the second os.path.exists(clangd_executable_path) check fails immediately afterwards.

Common situations: Upstream clangd release archive layout changed so the binary lands in a different subpath; corrupted/partial download extracted without the binary; disk space or permission problems during extraction; stale/corrupted install directory cache.

Related errors

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