oraios/serena · error · RuntimeError

Failed to check or install Solargraph

Error message

Failed to check or install Solargraph: {error_msg}
Please try installing manually: gem install solargraph

What it means

SolidLSP's Ruby server (Solargraph) tries to verify or auto-install the solargraph gem by shelling out to gem/bundle. If that subprocess exits non-zero (CalledProcessError), _setup_runtime_dependencies raises this RuntimeError and points the developer at the manual install command. It means the language server binary could not be provisioned, so the server cannot start.

Solutions

  1. Run `gem install solargraph` manually and confirm `gem exec solargraph --version` works on PATH.
  2. Ensure Ruby and the gem CLI are installed and on PATH (`ruby -v`, `gem -v`).
  3. For Bundler projects, add `gem "solargraph"` to the Gemfile and run `bundle install`.
  4. Check network/proxy access to rubygems.org and set GEM_HOME/GEM_PATH if gems install to a non-default location.

Example fix

// before: server init fails in slim CI image
# Dockerfile: ruby:slim
// after
# Dockerfile: ruby:slim
RUN gem install solargraph --no-document
Defensive patterns

Strategy: validation

Validate before calling

import shutil, subprocess
if not shutil.which("gem"):
    raise SystemExit("Ruby gem CLI required")
r = subprocess.run(["gem", "list", "solargraph", "-e"], capture_output=True, text=True)
if "solargraph" not in r.stdout:
    subprocess.run(["gem", "install", "solargraph", "--no-document"], check=True)

Type guard

def solargraph_available() -> bool:
    import shutil, subprocess
    return bool(shutil.which("gem")) and subprocess.run(
        ["gem", "list", "solargraph", "-e"], capture_output=True, text=True
    ).returncode == 0 and "solargraph" in subprocess.run(
        ["gem", "list", "solargraph", "-e"], capture_output=True, text=True
    ).stdout

Try / catch

try:
    server = SolargraphLanguageServer(config, repo_root, settings)
except RuntimeError as e:
    if "gem install solargraph" in str(e):
        subprocess.run(["gem", "install", "solargraph", "--no-document"], check=True)
        server = SolargraphLanguageServer(config, repo_root, settings)
    else:
        raise

Prevention

When it happens

Trigger: Instantiating the Solargraph language server when `gem exec solargraph` (or the dependency check) fails: gem/bundle not on PATH, no network for `gem install solargraph`, or a Bundler-project install command failing with a non-zero exit code.

Common situations: Docker/CI images without Ruby gems, missing write permissions to the gem directory (GEM_HOME), corporate proxies blocking rubygems.org, or a project Gemfile.lock that pins no solargraph version.

Related errors

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

Appendix: source

Thrown at src/solidlsp/language_servers/solargraph.py:192

                    "installCommand": "gem install solargraph -v 0.51.1",
                    "binaryName": "solargraph",
                    "archiveType": "gem",
                }
            ]

            dependency = runtime_dependencies[0]
            try:
                result = subprocess_run(
                    ["gem", "list", "^solargraph$", "-i"], check=False, capture_output=True, text=True, cwd=repository_root_path
                )
                if result.stdout.strip() == "false":
                    log.info("Installing Solargraph...")
                    subprocess_run(dependency["installCommand"].split(), check=True, capture_output=True, cwd=repository_root_path)

                return "gem exec solargraph"
            except subprocess.CalledProcessError as e:
                error_msg = e.stderr.decode() if e.stderr else str(e)
                raise RuntimeError(
                    f"Failed to check or install Solargraph: {error_msg}\nPlease try installing manually: gem install solargraph"
                ) from e
        else:
            raise RuntimeError(
                "This appears to be a Bundler project, but solargraph is not available. "
                "Please add 'gem \"solargraph\"' to your Gemfile and run 'bundle install'."
            )

    @staticmethod
    def _detect_rails_project(repository_root_path: str) -> bool:
        """
        Detect if this is a Rails project by checking for Rails-specific files.
        """
        rails_indicators = [
            "config/application.rb",
            "config/environment.rb",
            "app/controllers/application_controller.rb",
            "Rakefile",

View on GitHub (pinned to 7fcbca7e62)