Troubleshoot Rust issues
If compiling the Substrate node template fails, the problem is most likely to be caused by how Rust is configured in your development environment. This section suggests how you can diagnose and fix configuration issues.
Check your current configuration
To see information about the Rust toolchain that you are currently using, run the following command:
This command displays output similar to the following Ubuntu example:
Default host: x86_64-unknown-linux-gnu rustup home: /home/user/.rustup installed toolchains -------------------- stable-x86_64-unknown-linux-gnu (default) nightly-2020-10-06-x86_64-unknown-linux-gnu nightly-x86_64-unknown-linux-gnu installed targets for active toolchain -------------------------------------- wasm32-unknown-unknown x86_64-unknown-linux-gnu active toolchain ---------------- stable-x86_64-unknown-linux-gnu (default) rustc 1.50.0 (cb75ad5db 2021-02-10)
In this example, the default toolchain is from the
stable release channel for Linux running on x8664 architecture.
The sample output also indicates that the `nightly-x8664-unknown-linux-gnu` toolchain is installed and there are two targets installed:
x86_64-unknown-linux-gnuthe native Rust target for Linux.
wasm32-unknown-unknownthe WebAssembly target.
This environment also has the
nightly-2020-10-06-x86_64-unknown-linux-gnu toolchain installed, but this toolchain is only used if explicitly specified as a command-line option.
For an example of specifying a specific toolchain as a command line option, see Specify a nightly version.
Use the nightly release channel for WebAssembly
Substrate uses WebAssembly (Wasm) to produce a portable blockchain runtime.
You must configure the Rust compiler to use
nightly builds to allow you to
compile Substrate runtime code to the Wasm target.
Update the toolchain
In general, you should always use the latest versions of Rust
nightly builds because changes in Substrate often depend on upstream changes in the Rust
nightly compiler build.
To ensure your Rust compiler is always up to date, you should run the following commands:
rustup update rustup update nightly rustup target add wasm32-unknown-unknown --toolchain nightly
rustup update updates both the
stable toolchains to use the most recent release.
If you are unable to compile the WebAssembly target after updating the
nightly toolchain, you can roll back to an earlier version of the toolchain and specify that version as a command-line option.
For more information about getting an earlier version of the
nightly toolchain and specifying the version to use as a command-line option,downgrade the toolchain.
Use a specific nightly toolchain
If you want to guarantee that your build works on your computer as you update Rust and other dependencies, you should use a specific Rust
nightly toolchain that you know to be compatible with the version of Substrate you are using.
How you identify and communicate the specific
nightly toolchain version to use for a project can vary.
For example, Polkadot publishes this information in its release notes.
After you identify the specific
nightly toolchain version to use, you can install it in your development environment by running a command similar to the following:
rustup install nightly-<yyyy-MM-dd>
rustup install nightly-2022-02-16
After you install a specific version of the nightly toolchain, configure the WebAssembly target to use it by running a command similar to the following:
rustup target add wasm32-unknown-unknown --toolchain nightly-<yyyy-MM-dd>
rustup target add wasm32-unknown-unknown --toolchain nightly-2022-02-16
Specify the toolchain in an environment variable
You can set the
WASM_BUILD_TOOLCHAIN environment variable to specify the version of the
nightly toolchain to use for compiling WebAssembly.For example:
WASM_BUILD_TOOLCHAIN=nightly-<yyyy-MM-dd> cargo build --release
This command builds the runtime using the specified nightly toolchain.
The rest of project is compiled using the default toolchain, that is, the latest version of the
stable toolchain that you have installed.
Downgrade the nightly toolchain
If your computer is configured to use the latest Rust
nightly toolchain and you want to downgrade to a specific nightly version,you must first uninstall the latest
For example, you can remove the latest
nightly toolchain, then use a specific version of the
nightly toolchain by running commands similar to the following:
rustup uninstall nightly rustup install nightly-<yyyy-MM-dd> rustup target add wasm32-unknown-unknown --toolchain nightly-<yyyy-MM-dd>
Ensure PATH is set correctly
If after installing Rust the commands don't seem to work, showing errors such as
command not found: rustup, make sure it your PATH is configured correctly.
rustup installer installs by default to the bash profile (on mac). If you are using another shell, make sure to add this line to your profile (e.g.
Installing cmake or protobuf for M1 macOS users
Currently, there are issues compiling the Substrate node when using the packages that are pre-installed on macOS computers with the M1 chip.
error: failed to run custom build command for prost-build v0.10.4
If you see this error, there are two solutions.
cmakeby running the following command:
brew install cmake
- Install the correct pre-compiled
protocby running the following set of commands:
git clone https://github.com/protocolbuffers/protobuf.git cd protobuf brew install autoconf brew install automake brew install Libtool autoreconf -i ./autogen.sh ./configure make make check sudo make install export PATH=/opt/usr/local/bin:$PATH