oraios/serena · error · RuntimeError

Error checking Ruby installation: {error_msg}. Please ensure

Error message

Error checking Ruby installation: {error_msg}. Please ensure Ruby is properly installed and in PATH.

What it means

During `_setup_runtime_dependencies` the wrapper shells out to `ruby --version` with `check=True`; when Ruby itself runs but the command fails (non-zero exit), the `subprocess.CalledProcessError` is caught and re-raised as this RuntimeError including Ruby's stderr, telling the user to ensure Ruby is properly installed and in PATH.

Source

Thrown at src/solidlsp/language_servers/ruby_lsp.py:182

        # Check if Ruby is installed
        try:
            result = subprocess_run(ruby_cmd + ["--version"], check=True, capture_output=True, cwd=repository_root_path, text=True)
            ruby_version = result.stdout.strip()
            log.info(f"Ruby version: {ruby_version}")

            # Extract version number for compatibility checks
            import re

            version_match = re.search(r"ruby (\d+)\.(\d+)\.(\d+)", ruby_version)
            if version_match:
                major, minor, patch = map(int, version_match.groups())
                if major < 2 or (major == 2 and minor < 6):
                    log.warning(f"Warning: Ruby {major}.{minor}.{patch} detected. ruby-lsp works best with Ruby 2.6+")

        except subprocess.CalledProcessError as e:
            error_msg = e.stderr if isinstance(e.stderr, str) else e.stderr.decode() if e.stderr else "Unknown error"
            raise RuntimeError(
                f"Error checking Ruby installation: {error_msg}. Please ensure Ruby is properly installed and in PATH."
            ) from e
        except FileNotFoundError as e:
            raise RuntimeError(
                "Ruby is not installed or not found in PATH. Please install Ruby using one of these methods:\n"
                "  - Using mise:  mise install ruby && mise use ruby  (https://mise.jdx.dev)\n"
                "  - Using rbenv: rbenv install 3.0.0 && rbenv global 3.0.0\n"
                "  - Using asdf:  asdf install ruby 3.0.0 && asdf global ruby 3.0.0\n"
                "  - Using RVM:   rvm install 3.0.0 && rvm use 3.0.0 --default\n"
                "  - System package manager (brew install ruby, apt install ruby, etc.)"
            ) from e

        # Check for Bundler project (Gemfile exists)
        gemfile_path = os.path.join(repository_root_path, "Gemfile")
        gemfile_lock_path = os.path.join(repository_root_path, "Gemfile.lock")
        is_bundler_project = os.path.exists(gemfile_path)

        if is_bundler_project:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Fix the Ruby manager state: run `rbenv rehash` / reinstall the active version (`rbenv install <ver> && rbenv global <ver>`) or `asdf resinstall ruby`
Verify `ruby --version` works directly in the launching shell and repair/reinstall Homebrew or system Ruby if it errors
Point PATH at a known-good Ruby before instantiating, or reinstall Ruby via mise/rvm

Example fix

# before
$ ruby --version  # rbenv: version '3.1.2' is not installed (exit 1)

# after
$ rbenv install 3.1.2 && rbenv global 3.1.2 && rbenv rehash
$ ruby --version  # ruby 3.1.2p20 (exit 0)

Defensive patterns

Strategy: try-catch

Validate before calling

import subprocess
try:
    subprocess.run(["ruby", "--version"], capture_output=True, check=True)
except (subprocess.CalledProcessError, FileNotFoundError) as e:
    raise SystemExit(f"Ruby is broken or missing; fix ruby before starting: {e}")

Type guard

def ruby_works() -> bool:
    try:
        return subprocess.run(["ruby", "--version"], capture_output=True, check=False).returncode == 0
    except FileNotFoundError:
        return False

Try / catch

try:
    server = RubyLSP(config, repo_root, settings)
except RuntimeError as e:
    if "Error checking Ruby installation" in str(e):
        logger.error("ruby --version failed; fix rbenv/asdf state or reinstall Ruby: %s", e)
        raise SystemExit(1) from e
    raise

Prevention

Keep rbenv/rvm/asdf shims healthy: rehash after installs and remove shims for deleted versions
Verify `ruby --version` in CI before jobs that instantiate ruby-lsp
Use mise/rvm with pinned versions committed to the repo so all environments match

When it happens

Trigger: Constructing ruby-lsp when the `ruby --version` invocation exits non-zero with stderr output — e.g. a corrupted Ruby install, a ruby wrapper script (rbenv shims, ASDF) failing because its underlying version is gone, or permission/ABI errors executing the binary.

Common situations: rbenv/rvm/asdf shim pointing at an uninstalled Ruby version; a partially upgraded Homebrew Ruby with broken dylibs; container image where /usr/bin/ruby is a stub that errors; disk/permission issues making the binary unexecutable.

Related errors

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