rls/debugging.md

Debugging and Troubleshooting

Some tips and advice for debugging issues with the RLS. Many of these issues are specific to the Visual Studio Code extension.

Where we mention settings, below, we usually mean Visual Studio Code's settings. These can be set per-user and per-project, and can be found in the File > Preferences > Settings menu.

Common problems

Missing Rustup

The only external component that the VSCode extension requires is Rustup. It will install everything else (RLS, even Rust) itself.

You can install Rustup from rustup.rs. The extension should warn you if it is not present. See the extension section below for more issues.

Missing RLS component

stable, beta toolchains

You might see an error like toolchain 'stable-x86_64-unknown-linux-gnu' does not contain component 'rls' for target 'x86_64-unknown-linux-gnu', however we guarantee for stable and beta toolchains to contain the rls component. This might be rustup.rs issue. Plese submit additional information to above issue if you'd like. If you face this case, you may have to reinstall the toolchain.

$ rustup uninstall stable
$ rustup install stable
$ rustup component add rls

nightly toolchain

You might see an error like toolchain 'nightly-x86_64-unknown-linux-gnu' does not contain component 'rls' for target 'x86_64-unknown-linux-gnu'.

This is due to a nightly release missing the RLS component. That happens occasionally when the RLS cannot be built with the current compiler. To work around this issue you can use an RLS from the beta or stable channels, wait for a new nightly which does contain the RLS component, or use an older nightly which includes the RLS component. To do the latter follow these instructions, then avoid rustup update.

Out of date components

Run rustup update from the command line to make sure Rust, the RLS, and associated data are all up to date.

Project has both a library and a binary

The RLS can currently only work with one target at a time. By default, the RLS works with the binary, if there is only one. You can build the library by setting rust.build_lib to true (this is often most useful). If you have multiple binaries, you can specify one to work with using rust.build_bin.

Auto-detection for some of this should be in the next release.

Opening a Rust file outside of a project

Before opening a Rust file, the RLS needs to be aware of the whole crate. That means you need to have opened the folder containing Cargo.toml in VSCode before opening a Rust file (which triggers loading the Rust extension).

Information for paths

If you have a path such as foo::bar::baz, the RLS only has information for the last segment of the path. That means you can only 'goto def' or get type information on hover for baz, not for foo or bar. This is a limitation in the Rust compiler, but should be addressed at some point.

Tests, examples

The RLS currently only works with the main part of a crate. It does not work with the tests or examples folders.

The RLS can give information about unit tests, you need to set rust.cfg_test to true (note that this will cause a lot of 'unused code' warnings, which is why it is off by default).

Stale data

Stale data can often trip up or slow down the RLS. It can be worth running cargo clean and/or deleting the entire target directory for your crate. You'll need to restart the extension after doing this to get a proper rebuild.

It is also possible (but rarer) that Rustup gets into a bad place with stale data. You can reinstall rustup and/or delete its cache (in ~/.rustup) to try and solve this.

Deprecated environment variables

If you were using early versions of the RLS and extension, you might have used RLS_PATH or RLS_ROOT env vars. These can cause issues now, so remove them from your environment (this won't be necessary with the next release of the extension).

Extension issues

We recommend using our VSCode extension. Note that there are other VSCode extensions.

Ensure the extension and VSCode is up to date. You can check the latest version of VSCode on their website. You can see your version in the Help > About menu item. VSCode should tell you if it or your extension are not up to date.

The extension must be able to run Rustup. If Rustup is installed, it must be in your PATH. Note that if you run VSCode from an icon or launcher, the PATH may not be the same as from a terminal. You can check this issue by running VSCode from your terminal (code should work).

Project issues

It can be useful to determine if a problem is with your environment or with a project. Try running the VSCode extension with a very simple project. Use cargo new foo --bin to create a new project called foo, open the foo folder in VSCode. Add a local variable and a use of it, see if the RLS gives you the type of the variable on hover and if you can jump to its definition.

If the above works, then you probably have project issues. If it doesn't, then there is a problem with the environment.

If a project has a lot of dependencies, initial indexing might take a long time. In general, initial indexing should take about the same time as a full compile of the project (usually a little less time, but that depends).

If the primary crate of a project is large, it probably won't work well with the RLS (too slow). Exactly what 'large' means here will depend on how fast your machine is and how tolerant of latency you are.

Projects with Cargo workspaces will not work (for now).

Projects with non-Cargo build systems will not work (you might be able to make this work with some effort, talk to nrc on Discord).

Rarely, there are problems with the RLS's build model. You can try running cargo check on the command line to emulate the build model outside of the IDE.

Crates with large data files

Some crates can have surprisingly large data files. Large data files can slow down the RLS to the point of crashing (or appearing to crash). Check the json files in the target/rls/deps/save-analysis directory. Anything over 1mb is suspicious. You can test if this is important by deleting the json file(s) and restarting the extension (you'd have to do this every time you do a full build, for example after cargo clean or updating the toolchain).

If you find such large data files, please report an issue on this repo. We can try to optimise the data, or blacklist the crate.

Racer vs compiler issues

The RLS uses Racer for code completion, and the compiler for everything else (such as type on hover). If you are getting code completion options but not type on hover, etc., then there is probably an issue with the RLS getting data from the compiler. If you have type on hover, but poor code completion, then it is probably a Racer issue.

Racer and the rest of the RLS use different data sources for indexing the standard libraries. If you have Racer problems with the standard libraries, then it is worth checking the rust-source component. If Racer is working, but other things are not, it is worth checking the rust-analysis component (both components are delivered by Rustup).

Logging

When using VSCode extension, you can view error messages and logging in the Output window, under View > Output, in the 'Rust Language Server' channel that can be selected in the dropdown menu on the right of the panel.

To see more info in the logs, set RUST_LOG=rls=debug in your environment. You can also set RUST_LOG=rls_analysis=debug to see logging specific to the data analysis. In general, these will be printed to the standard error stream of the server.

If you are seeing crashes in the logs, you can get a backtrace by setting RUST_BACKTRACE=1.

You can also dump to a file by setting rust-client.logToFile to true in the VSCode extension. The file will be in the project root; each time you start the extension, you'll get a new file.

You can get more info about VSCode and the extension itself by running VSCode with --verbose. However, I have only rarely found this to be useful. You can also use VSCode's debugger to debug the extension. This can be useful if the extension hangs.

It might be useful to find the rls process and attach a debugger to it. However, with an optimised build and no debug symbols, this is not likely to be useful.

Library issues

If you get an error like error while loading shared libraries while starting up the RLS, you should try the following:

On Linux:

export LD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$LD_LIBRARY_PATH

On MacOS (this might only work if SIP is disabled (depending on how you run the RLS), you could modify the environment in the client):

export DYLD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$DYLD_LIBRARY_PATH

(This should not happen if you are using Rustup, only if building and running from source).

Getting more help

Please feel free to open an issue to discuss any problem.

If you use Discord, you can ask in #dev-tools on the Rust lang server. You can ping nrc.