oraios/serena · error · RuntimeError

Crystalline (Crystal language server) is not installed or no

Error message

Crystalline (Crystal language server) is not installed or not in PATH.
Please install it from https://github.com/elbywan/crystalline
and make sure the 'crystalline' binary is available on your PATH.

What it means

Raised by _find_crystalline when shutil.which('crystalline') returns None, i.e. the Crystalline language server binary is not installed or not on PATH. Unlike other servers in this library, Crystalline is not auto-downloaded, so the user must install it themselves.

Source

Thrown at src/solidlsp/language_servers/crystal_language_server.py:60

            config,
            repository_root_path,
            ProcessLaunchInfo(cmd=crystal_ls_path, cwd=repository_root_path),
            "crystal",
            solidlsp_settings,
        )
        self._initialization_timestamp: float | None = None

    @staticmethod
    def _find_crystalline() -> str:
        """
        Find the Crystalline executable on PATH.

        :return: path to the Crystalline executable
        :raises RuntimeError: if Crystalline is not found
        """
        path = shutil.which("crystalline")
        if path is None:
            raise RuntimeError(
                "Crystalline (Crystal language server) is not installed or not in PATH.\n"
                "Please install it from https://github.com/elbywan/crystalline\n"
                "and make sure the 'crystalline' binary is available on your PATH."
            )
        return path

    def _wait_for_compilation(self) -> None:
        """
        Wait for Crystalline to finish its initial compilation.

        Crystalline compiles the project on startup using the Crystal compiler.
        Definition requests will fail if sent before compilation completes.
        """
        if self._initialization_timestamp is None:
            return

        elapsed = time.time() - self._initialization_timestamp
        remaining_delay = max(0, _MIN_COMPILATION_DELAY - elapsed)

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install crystalline (download a release binary from https://github.com/elbywan/crystalline/releases or build with `shards build`)
Place/symlink the `crystalline` binary into a directory on PATH (e.g. /usr/local/bin)
Verify with `which crystalline` in the same environment that runs the library
If using a version manager, ensure its env vars are loaded for the service user

Example fix

// before
$ which crystalline # (nothing)
// after
curl -L https://github.com/elbywan/crystalline/releases/latest/download/crystalline-x86_64-unknown-linux-gnu -o /usr/local/bin/crystalline
chmod +x /usr/local/bin/crystalline
which crystalline # /usr/local/bin/crystalline

Defensive patterns

Strategy: validation

Validate before calling

import shutil
def ensure_crystalline() -> str:
    path = shutil.which("crystalline")
    if path is None:
        raise SystemExit(
            "Install crystalline from https://github.com/elbywan/crystalline "
            "and put it on PATH before starting the Crystal language server"
        )
    return path

Type guard

def crystalline_available() -> bool:
    import shutil
    return shutil.which("crystalline") is not None

Try / catch

try:
    server = CrystalLanguageServer(repo_path)
except RuntimeError as e:
    if "Crystalline" in str(e):
        install_crystalline_from_release()  # download binary into /usr/local/bin
        server = CrystalLanguageServer(repo_path)
    else:
        raise

Prevention

Install crystalline in your dev container / CI image as a setup step
Ensure version-manager environments (asdf, mise) are activated for service users
Add `which crystalline` to preflight checks before starting LSP sessions
Symlink manually built binaries into a standard PATH directory

When it happens

Trigger: Instantiating the Crystal language server (CrystalLanguageServer.__init__) on a machine where no `crystalline` executable is resolvable via PATH.

Common situations: Fresh machines/CI containers without Crystal tooling, crystalline installed but not in the PATH of the process (e.g. installed in ~/.local/bin or via asdf not activated in the service environment), or the binary named differently after a manual build.

Related errors

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