The following FAQ provides solutions to common issues running and using Solargraph.
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:
- Add solargraph to your Gemfile and
bundle exec yard gems.
bundle exec to start the language server. In VS Code, you can do this by setting the
solargraph.useBundler preference to
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.
In VS Code, Solargraph makes an attempt to detect the correct version of Ruby to run based on your workspace environment.
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
zsh shells are offically supported.
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.
The Atom extension uses the same techniques as the VS Code extension to integrate with rvm/rbenv, so the same suggestions are mostly applicable.
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:
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:
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.