src/tools/rls/debugging.md - toolchain/rustc - Git at Google


            
            # 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](https://www.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](https://github.com/rust-lang/rustup.rs/issues/1626).

            
            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](https://github.com/rust-lang/rls-vscode/issues/181#issue-269383659),

            
            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](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust).

            
            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](https://code.visualstudio.com/). 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](https://github.com/rust-lang/rls/issues/new)

            
            to discuss any problem.


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

            
            ping nrc.
	# 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](https://www.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](https://github.com/rust-lang/rustup.rs/issues/1626).
	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](https://github.com/rust-lang/rls-vscode/issues/181#issue-269383659),
	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](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust).
	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](https://code.visualstudio.com/). 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](https://github.com/rust-lang/rls/issues/new)
	to discuss any problem.

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