tracel-ai/burn · critical

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

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.

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)

Solutions

1. Add the flex feature to the burn dependency in Cargo.toml, e.g. burn = { version = "...", features = ["flex"] }, and rebuild.
2. Alternatively enable a catch-all default_backend feature (burn = { features = ["default_backend-flex"] }) so BURN_DEVICE=flex resolves.
3. If flex is not intended, unset BURN_DEVICE or set it to a backend that is actually compiled in (e.g. ndarray, candle).
4. 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)

// 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");
}

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

• BURN_DEVICE=ndarray requested, but the 'ndarray' feature is
• Unknown BURN_DEVICE override: '{}'.
• Requires `autodiff` feature
• capture tensor operations must run inside CaptureDevice::cap
• capture tensor {} has no initialized value

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