ccls is not installed on your system. Please install ccls us

Error message

ccls is not installed on your system.
Please install ccls using your system package manager:
  Linux (Ubuntu/Debian): sudo apt-get install ccls
  Linux (Fedora/RHEL):   sudo dnf install ccls
  Linux (Arch):          sudo pacman -S ccls
  macOS (Homebrew):      brew install ccls
  Windows:               choco install ccls

For build instructions and more details, see:
https://github.com/MaskRay/ccls/wiki/Build

What it means

_get_or_install_core_dependency raises FileNotFoundError because ccls has no managed prebuilt install: the library relies on a system-installed ccls binary and throws this instructive error when shutil.which('ccls') finds nothing. A ls_path override in ls_specific_settings can bypass the PATH lookup.

Source

Thrown at src/solidlsp/language_servers/ccls_language_server.py:88

    @override
    def is_ignored_dirname(self, dirname: str) -> bool:
        return (
            super().is_ignored_dirname(dirname)
            or dirname == ".ccls-cache"
            or (is_unreal_engine_project(self.repository_root_path) and dirname in UE_IGNORED_DIRNAMES)
        )

    class DependencyProvider(LanguageServerDependencyProviderSinglePath):
        def _get_or_install_core_dependency(self) -> str:
            """
            Resolve ccls path from system or raise helpful error if missing.
            Allows override via ls_specific_settings[language].ls_path.
            """
            import shutil

            ccls_path = shutil.which("ccls")
            if not ccls_path:
                raise FileNotFoundError(
                    "ccls is not installed on your system.\n"
                    "Please install ccls using your system package manager:\n"
                    "  Linux (Ubuntu/Debian): sudo apt-get install ccls\n"
                    "  Linux (Fedora/RHEL):   sudo dnf install ccls\n"
                    "  Linux (Arch):          sudo pacman -S ccls\n"
                    "  macOS (Homebrew):      brew install ccls\n"
                    "  Windows:               choco install ccls\n\n"
                    "For build instructions and more details, see:\n"
                    "  https://github.com/MaskRay/ccls/wiki/Build"
                )
            log.info(f"Using system-installed ccls at {ccls_path}")
            return ccls_path

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

    def _create_base_initialize_params(self) -> dict:
        """

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install ccls via the system package manager (apt/dnf/pacman/brew/choco as listed in the message)
Set ls_specific_settings[<language>].ls_path to the full path of a ccls binary you built or downloaded
Ensure the install location is on PATH for the process running the language server (`which ccls` to verify)
Reconnect/restart the server after installing so the PATH check re-runs

Example fix

// before
# no ccls on PATH -> FileNotFoundError
// after
sudo apt-get install ccls
# or, with a custom build:
{"ls_specific_settings": {"cpp": {"ls_path": "/opt/ccls/bin/ccls"}}}

Defensive patterns

Strategy: validation

Validate before calling

import shutil
assert shutil.which("ccls"), "Install ccls (apt/dnf/pacman/brew/choco) or set ls_specific_settings[<lang>].ls_path before starting the CCLS server"

Try / catch

try:
    server = CCLSLanguageServer(...)
except FileNotFoundError as e:
    if "ccls is not installed" in str(e):
        raise SystemExit("Install ccls via your package manager, or point ls_path at an existing binary")
    raise

Prevention

Install ccls up front on dev machines and CI images
Set ls_specific_settings ls_path when using a custom-built ccls
Verify `which ccls` in the exact environment that launches Serena

When it happens

Trigger: Starting the CCLS language server for C/C++ when `ccls` is not resolvable on PATH and no ls_specific_settings[language].ls_path override is configured.

Common situations: ccls not installed (it is not in default repos on many distros); installed via source/brew into a directory not on the server process's PATH; running inside a container without ccls; PATH differences between the IDE and the shell.

Related errors

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