oraios/serena · error · FileNotFoundError

Gleam is not installed or not in PATH. Please install the Gl

Error message

Gleam is not installed or not in PATH.
Please install the Gleam compiler from https://gleam.run/getting-started/installing/
and ensure the 'gleam' binary is available on your PATH.
The Gleam language server is bundled with the compiler and is started via `gleam lsp`.

What it means

FileNotFoundError thrown while discovering the Gleam compiler executable. The Gleam language server is bundled with the compiler and started via `gleam lsp`, so without the `gleam` binary on PATH the server cannot be launched. The library does not auto-install Gleam.

Source

Thrown at src/solidlsp/language_servers/gleam_language_server.py:70

        self._progress_lock = threading.Lock()
        self._active_progress_tokens: set[str | int] = set()
        self._first_progress_seen = threading.Event()
        self._idle = threading.Event()
        self._idle.set()  # optimistic: assume ready until a $/progress begin arrives

    def _create_dependency_provider(self) -> LanguageServerDependencyProvider:
        return self.DependencyProvider(self._custom_settings, self._ls_resources_dir)

    class DependencyProvider(LanguageServerDependencyProviderSinglePath):
        def _get_or_install_core_dependency(self) -> str:
            """
            Discover the Gleam compiler executable on PATH.

            :return: path to the ``gleam`` binary
            :raises FileNotFoundError: if ``gleam`` is neither on PATH nor provided via ``ls_path``
            """
            gleam_binary = shutil.which("gleam")
            if gleam_binary is None:
                raise FileNotFoundError(
                    "Gleam is not installed or not in PATH.\n"
                    "Please install the Gleam compiler from https://gleam.run/getting-started/installing/\n"
                    "and ensure the 'gleam' binary is available on your PATH.\n"
                    "The Gleam language server is bundled with the compiler and is started via `gleam lsp`."
                )
            return gleam_binary

        def _create_launch_command(self, core_path: str) -> list[str]:
            # `gleam lsp` runs the language server over stdio.
            return [core_path, "lsp"]

    @override
    def is_ignored_dirname(self, dirname: str) -> bool:
        # Gleam writes compiled output and downloaded dependencies under build/.
        return super().is_ignored_dirname(dirname) or dirname == "build"

    @override

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install Gleam following https://gleam.run/getting-started/installing/ (e.g. `curl -fsSL https://gleam.run/install.sh | sh`)
Verify with `which gleam` / `gleam --version` in the same shell/environment that runs the library
If installed via asdf/mise, activate the shim so it appears on PATH for non-interactive processes, or point ls_path at the absolute gleam binary
Set ls_path in serena_config.yml under ls_specific_settings.gleam to the absolute path of the gleam binary

Example fix

// before
gleam --version  # command not found
// after
curl -fsSL https://gleam.run/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
gleam --version

Defensive patterns

Strategy: validation

Validate before calling

import shutil
def ensure_gleam_available():
    if shutil.which('gleam') is None:
        raise FileNotFoundError("'gleam' not on PATH. Install from https://gleam.run/getting-started/installing/")

Prevention

Run `gleam --version` as a smoke test in setup scripts
Use absolute paths or ls_path in containers/CI where PATH varies
Ensure version-manager shims (asdf/mise) are exported for non-interactive shells
Pin the Gleam install in your Dockerfile/CI image

When it happens

Trigger: Instantiating the Gleam language server when shutil.which('gleam') returns None, i.e. gleam is neither on PATH nor provided via the ls_path setting.

Common situations: Gleam never installed; installed via a version manager (e.g. asdf/mise) whose PATH isn't loaded in the daemon/CI environment; installed inside a project-local toolchain not exported to PATH.

Related errors

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