I have a gem installed on my system and required in my code, but I don’t get any intellisense for it in my IDE (no autocomplete, documentation, etc.).

The most common reason for a gem to be missing from your intellisense is missing YARD documentation. You can generate the documentation by running yard gems on the command line.

I have a project that keeps a local directory of cached or vendored gems, and I don’t get any intellisense for them in my IDE.

You need to use Bundler to document cached/vendored gems and make them available to the language server:

1. Add solargraph to your Gemfile and bundle install.
2. Run bundle exec yard gems.
3. Use bundle exec to start the language server. In VS Code, you can do this by setting the solargraph.useBundler preference to true.

I’m using rbenv or rvm, and when I open a project in my editor, Solargraph runs a different version of Ruby than I expected.

VS Code

In VS Code, Solargraph makes an attempt to detect the correct version of Ruby to run based on your workspace environment.

Linux

Confirm that your environment is configured correctly from the command-line.

$ cd /path/to/workspace
$ ruby -v
$ solargraph -v

If the Ruby and Solargraph versions are correct but Solargraph still doesn’t work in the editor, try opening it from the command-line, e.g., run code . (note the dot at the end of the command). If that works as expected, there might be a problem with how your shell is integrated with rvm/rbenv. Only bash and zsh shells are offically supported.

MacOS

The suggestions for Linux should also work on MacOS, with one exception: you need to add the code command to your PATH in order to run it from the command line. See Visual Studio Code on MacOS for more information.

Choosing a Specific Executable

If your editor still can’t find the solargraph executable, you can try referencing it by its absolute path in the solargraph.commandPath setting. See the vscode-solargraph or atom-solargraph documentation for more information.

Atom

The Atom extension uses the same techniques as the VS Code extension to integrate with rvm/rbenv, so the same suggestions are mostly applicable.

Other Clients

For editors other than VS Code or Atom, please refer to the software or extension’s own documentation.

Whenever I use the Solargraph language server, the OS reports extremely high CPU usage for its process.

CPU usage sometimes spikes when the language server initializes, especially for very large workspaces. It should go back to normal after the initialization is complete.

If the CPU load stays consistently high, see the Performance section for additional tips on making Solargraph run faster, or try running a scan to identify problems.

I get errors building native extensions on MacOS.

Errors building native extensions usually mean you don’t have the Ruby development headers installed. The process for installing depends on your MacOS version.

First, you should make sure you have xcode installed:

xcode-select --install
sudo xcodebuild -license

MacOS 10.14 stopped installing the Ruby headers by default. You might need to install them yourself with some variation of this:

open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg

This might be necessary on XCode 11:

sudo xcode-select --switch /Library/Developer/CommandLineTools
sudo xcode-select --switch /Applications/Xcode.app

There’s more discussion about this issue, including further references, in a vscode-solargraph issue on GitHub.