oraios/serena · error · RuntimeError

Found a Go version but gopls is not installed. Please instal

Error message

Found a Go version but gopls is not installed.
Please install gopls as described in https://pkg.go.dev/golang.org/x/tools/gopls#section-readme

After installation, make sure it is added to your PATH (it might be installed in a different location than Go).

What it means

RuntimeError raised in Gopls._setup_runtime_dependency when a Go toolchain was found but the gopls language server binary is missing. The library distinguishes this from error 232 so the user knows only the language-server component is absent. gopls is not auto-installed here.

Source

Thrown at src/solidlsp/language_servers/gopls.py:97

                return result.stdout.strip()
        except FileNotFoundError:
            return None
        return None

    @staticmethod
    def _setup_runtime_dependency() -> bool:
        """
        Check if required Go runtime dependencies are available.
        Raises RuntimeError with helpful message if dependencies are missing.
        """
        go_version = Gopls._get_go_version()
        if not go_version:
            raise RuntimeError(
                "Go is not installed. Please install Go from https://golang.org/doc/install and make sure it is added to your PATH."
            )

        gopls_version = Gopls._get_gopls_version()
        if not gopls_version:
            raise RuntimeError(
                "Found a Go version but gopls is not installed.\n"
                "Please install gopls as described in https://pkg.go.dev/golang.org/x/tools/gopls#section-readme\n\n"
                "After installation, make sure it is added to your PATH (it might be installed in a different location than Go)."
            )

        return True

    def __init__(self, config: LanguageServerConfig, repository_root_path: str, solidlsp_settings: SolidLSPSettings):
        self._setup_runtime_dependency()

        super().__init__(config, repository_root_path, ProcessLaunchInfo(cmd="gopls", cwd=repository_root_path), "go", solidlsp_settings)
        self.request_id = 0

    def _create_base_initialize_params(self) -> dict:
        """
        Returns the initialize params for the Go Language Server.
        """

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install gopls: `go install golang.org/x/tools/gopls@latest`
Add the install location to PATH — typically `export PATH=$PATH:$(go env GOPATH)/bin`
Verify with `which gopls && gopls version` in the same environment that runs the library
If the Go upgrade replaced gopls, reinstall it with the @latest version

Example fix

// before
gopls version  # command not found
// after
go install golang.org/x/tools/gopls@latest
export PATH=$PATH:$(go env GOPATH)/bin
gopls version

Defensive patterns

Strategy: validation

Validate before calling

import shutil, subprocess
def ensure_gopls_installed():
    if shutil.which('go') is None:
        raise FileNotFoundError('Go toolchain required first')
    if shutil.which('gopls') is None:
        raise FileNotFoundError('gopls missing; run: go install golang.org/x/tools/gopls@latest')
    subprocess.run(['gopls', 'version'], check=True, capture_output=True)

Prevention

Always install gopls alongside Go in setup scripts
Add $(go env GOPATH)/bin to PATH in shell profiles and CI
Reinstall gopls after major Go upgrades
Smoke-test `gopls version` before language-server usage

When it happens

Trigger: Constructing the Gopls server when _get_go_version() succeeds but _get_gopls_version() returns falsy — i.e. `gopls version` fails or gopls is not on PATH.

Common situations: Fresh Go install that includes the toolchain but not gopls; gopls installed into GOBIN/GOPATH/bin (~/go/bin) which is not on PATH; gopls removed or broken after a Go toolchain upgrade.

Related errors

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