BURN_DEVICE=flex requested, but the 'flex' feature is not…

Error message

BURN_DEVICE=flex requested, but the 'flex' feature is not enabled.

What it means

This panic fires when the BURN_DEVICE environment variable selects the 'flex' backend but the burn build was compiled without the 'flex' feature (and without default_backend matching). Burn dispatches to a backend at device-construction time based on compile-time cargo features; a runtime env var cannot enable a backend that was not compiled in. The library panics immediately rather than silently falling back, so the misconfiguration is surfaced at startup.

Solutions

Add the flex feature to the burn dependency in Cargo.toml, e.g. burn = { version = "...", features = ["flex"] }, and rebuild.
Alternatively enable a catch-all default_backend feature (burn = { features = ["default_backend-flex"] }) so BURN_DEVICE=flex resolves.
If flex is not intended, unset BURN_DEVICE or set it to a backend that is actually compiled in (e.g. ndarray, candle).
Verify compiled features with `cargo tree -e features -i burn` or check the burn features docs before setting the env var.

Example fix

// before (Cargo.toml)
[dependencies]
burn = { version = "0.18", features = ["ndarray"] }
// BURN_DEVICE=flex ./app  -> panics

// after
[dependencies]
burn = { version = "0.18", features = ["flex"] }
// BURN_DEVICE=flex ./app  -> DispatchDevice::Flex(FlexDevice)

Defensive patterns

Strategy: validation

Validate before calling

// before constructing the device
let req = std::env::var("BURN_DEVICE").unwrap_or_default();
if req == "flex" && !cfg!(feature = "flex") && !cfg!(default_backend) {
    panic!("Rebuild with burn feature 'flex' or unset BURN_DEVICE");
}

Prevention

Keep the BURN_DEVICE values supported by your binary documented next to the burn features list in Cargo.toml.
Assert the env var against compiled features in a #[test] or startup check.
Use default_backend-* features so env overrides always resolve.

When it happens

Trigger: Running any Burn program with BURN_DEVICE=flex set in the environment while the crate was built without `features = ["flex"]` (and without a default_backend feature) on crates/burn-dispatch/src/device.rs:278 during DispatchDevice::from_env/default parsing.

Common situations: Copying a run command or Dockerfile from a project that uses the flex backend into a project whose Cargo.toml lacks the feature; CI images built with a reduced feature set; toggling BURN_DEVICE between experiments without rebuilding with the matching features.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/5fbc4782b4876890. Report an issue: GitHub.

Appendix: source

Thrown at crates/burn-dispatch/src/device.rs:278

                        return Self::Cube(CubeDevice::Cpu(Default::default()));
                        panic!("BURN_DEVICE=cpu requested, but the 'cpu' feature is not enabled.");
                    }
                    "tch" => {
                        #[cfg(feature = "tch")]
                        return Self::LibTorch(LibTorchDevice::default());
                        panic!("BURN_DEVICE=tch requested, but the 'tch' feature is not enabled.");
                    }
                    "remote" => {
                        #[cfg(feature = "remote")]
                        return Self::Remote(RemoteDevice::default());
                        panic!(
                            "BURN_DEVICE=remote requested, but the 'remote' feature is not enabled."
                        );
                    }
                    "flex" => {
                        #[cfg(any(feature = "flex", default_backend))]
                        return Self::Flex(FlexDevice);
                        panic!(
                            "BURN_DEVICE=flex requested, but the 'flex' feature is not enabled."
                        );
                    }
                    "ndarray" => {
                        #[cfg(feature = "ndarray")]
                        return Self::NdArray(NdArrayDevice::default());
                        panic!(
                            "BURN_DEVICE=ndarray requested, but the 'ndarray' feature is not enabled."
                        );
                    }
                    _ => panic!("Unknown BURN_DEVICE override: '{}'.", device_str),
                }
            }
        }

        // Spelled out per feature rather than left to `CubeDevice::default()`: that answers for
        // the runtimes *cubecl* compiled in, and cargo unifies features across a build, so a
        // workspace that also builds `burn-cuda` would hand this crate a CUDA default even when

View on GitHub (pinned to d16f7ba2ed)