Warning: this page has not been updated for Bevy 0.10 yet!

Strange Build Errors

Sometimes, you can get strange and confusing build errors when trying to compile your project.

Update your Rust

First, make sure your Rust is up-to-date. When using Bevy, you must use at least the latest stable version of Rust (or nightly).

If you are using rustup to manage your Rust installation, you can run:

rustup update

Clear the cargo state

Many kinds of build errors can often be fixed by forcing cargo to regenerate its internal state (recompute dependencies, etc.). You can do this by deleting the Cargo.lock file and the target directory.

rm -rf target Cargo.lock

Try building your project again after doing this. It is likely that the mysterious errors will go away.

This trick often fixes the broken build, but if it doesn't help you, your issue might require further investigation. Reach out to the Bevy community via GitHub or Discord, and ask for help.

If you are using bleeding-edge Bevy ("main"), and the above does not solve the problem, your errors might be caused by 3rd-party plugins. See this page for solutions.

New Cargo Resolver

Cargo recently added a new dependency resolver algorithm, that is incompatible with the old one. Bevy requires the new resolver.

If you are just creating a new blank Cargo project, don't worry. This should already be setup correctly by cargo new.

If you are getting weird compiler errors from Bevy dependencies, read on. Make sure you have the correct configuration, and then clear the cargo state.

Single-Crate Projects

In a single-crate project (if you only have one Cargo.toml file in your project), if you are using the latest Rust2021 Edition, the new resolver is automatically enabled.

So, you need either one of these settings in your Cargo.toml:

[package]
edition = "2021"

or

[package]
resolver = "2"

Multi-Crate Workspaces

In a multi-crate Cargo workspace, the resolver is a global setting for the whole workspace. It will not be enabled by default.

This can bite you if you are transitioning a single-crate project into a workspace.

You must add it manually to the top-level Cargo.toml for your Cargo Workspace:

[workspace]
resolver = "2"

What errors?

One common example is the "failed to select a version" error, which can look something like this:

error: failed to select a version for `web-sys`.
    ... required by package `wgpu v0.9.0`
    ... which is depended on by `bevy_wgpu v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_internal v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy-scratchpad v0.1.0 (C:\Users\Alice\Documentsevy-scratchpad)`
versions that meet the requirements `=0.3.50` are: 0.3.50

all possible versions conflict with previously selected packages.

  previously selected package `web-sys v0.3.46`
    ... which is depended on by `bevy_app v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_asset v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_audio v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy_internal v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy v0.5.0 (https://github.com/bevyengine/bevy#6a8a8c9d)`
    ... which is depended on by `bevy-scratchpad v0.1.0 (C:\Users\Alice\Documentsevy-scratchpad)`

failed to select a version for `web-sys` which could resolve this conflict

(there are many variations, yours might not be identical to the example above)

Another related error are seemingly-nonsensical compiler messages about conflicts with Bevy's internal types (like "expected type Transform, found type Transform").

Why does this happen?

Such errors are often caused by cargo's internal state being broken. Usually, it is because of dependencies not being resolved properly, causing cargo to try to link multiple versions of Bevy into your project. This often occurs when transitioning your project between the release and the git version of Bevy. Cargo remembers the versions it was previously using, and gets confused.