oraios/serena · error · FileNotFoundError

Clangd is not installed on your system. Please install clang

Error message

Clangd is not installed on your system.
Please install clangd using your system package manager:
  Ubuntu/Debian: sudo apt-get install clangd
  Fedora/RHEL: sudo dnf install clang-tools-extra
  Arch Linux: sudo pacman -S clang
See https://clangd.llvm.org/installation for more details.

What it means

_get_or_install_core_dependency raises FileNotFoundError when no prebuilt clangd binary is available for the platform and no system-installed clangd is found via shutil.which. The library first tries a managed prebuilt download, then falls back to the system clangd, and throws this actionable error if both are unavailable.

Source

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

                        binary_name=f"clangd_{clangd_version}/bin/clangd",
                        sha256="d3b329b3f58602c57ca6501d255147af1bccad3691b1cb0c12c258fcd2da1be3" if default_version else None,
                        allowed_hosts=CLANGD_ALLOWED_HOSTS,
                    ),
                ]
            )

            clangd_ls_dir = os.path.join(self._ls_resources_dir, "clangd")

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

            if dep is None:
                # No prebuilt binary available, look for system-installed clangd
                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"

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install clangd via the system package manager: sudo apt-get install clangd (Ubuntu/Debian), sudo dnf install clang-tools-extra (Fedora/RHEL), sudo pacman -S clang (Arch)
Install LLVM/clangd from https://clangd.llvm.org/installation and add its bin directory to PATH
Restart/reconnect the language server after installing so the detection re-runs

Example fix

// before
# clangd not found -> FileNotFoundError
// after
sudo apt-get install clangd
clangd --version  # verify

Defensive patterns

Strategy: validation

Validate before calling

import shutil
assert shutil.which("clangd"), "Install clangd: apt-get install clangd | dnf install clang-tools-extra | pacman -S clang (see clangd.llvm.org/installation)"

Try / catch

try:
    server = ClangdLanguageServer(...)
except FileNotFoundError as e:
    if "Clangd is not installed" in str(e):
        raise SystemExit("Install clangd via your package manager or LLVM binaries, then restart the server")
    raise

Prevention

Install clangd (not just clang) on dev machines and CI images — Fedora needs clang-tools-extra
Add LLVM install bin directories to PATH if installing clangd outside the package manager
Verify `clangd --version` in the same environment Serena runs in

When it happens

Trigger: Starting the clangd language server when deps.binary_path yields no prebuilt binary for the current platform and shutil.which('clangd') returns None.

Common situations: clangd not installed on the machine; platform without a managed prebuilt binary (unusual OS/arch); clang installed without the clangd component (e.g. needs clang-tools-extra on Fedora); PATH not including the LLVM install directory.

Related errors

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