tracel-ai/burn · critical

Unknown BURN_DEVICE override: '{}'.

Error message

Unknown BURN_DEVICE override: '{}'.

What it means

The BURN_DEVICE environment variable contained a value that matches no known backend arm in the dispatcher's match statement. Burn validates the override string against its list of compiled backends and panics on any unrecognized name rather than guessing or falling back to the default device.

Source

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

                        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
        // it was built with only `wgpu`. The order is the one a caller who did not choose would
        // want — a discrete accelerator, then the portable path, then the CPU.
        #[cfg(feature = "cuda")]
        return Self::Cube(CubeDevice::Cuda(Default::default()));

        #[cfg(feature = "metal")]
        return Self::Cube(CubeDevice::Wgpu(Default::default()));

        #[cfg(feature = "rocm")]
        return Self::Cube(CubeDevice::Hip(Default::default()));

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Set BURN_DEVICE to an exact supported identifier (check the match arms in crates/burn-dispatch/src/device.rs, e.g. candle, ndarray, flex, remote, or a cubecl runtime like wgpu/cuda).
2. Fix case sensitivity and whitespace: the value must be lowercase and trimmed (BURN_DEVICE=GPU is invalid).
3. Remove BURN_DEVICE entirely to use the default device resolution when no override is needed.
4. Grep your deployment/CI config for `BURN_DEVICE=` and validate every value against the enabled feature set.

Example fix

// before (deploy.sh)
export BURN_DEVICE=cuda   # unknown name -> panic

// after
export BURN_DEVICE=cudacompile   # or the exact runtime name, e.g.:
export BURN_DEVICE=candle

const VALID: &[&str] = &["candle", "ndarray", "flex", "remote", "wgpu", "cuda", "rocm", "vulkan", "metal"];
if let Ok(d) = std::env::var("BURN_DEVICE") {
    if !VALID.contains(&d.as_str()) {
        panic!("BURN_DEVICE='{}' is not a known backend name", d);
    }
}

When it happens

Trigger: Exporting BURN_DEVICE with a typo or unsupported value (e.g. BURN_DEVICE=cuda, BURN_DEVICE=gpu, BURN_DEVICE=Candle, BURN_DEVICE=tch) where the expected arm names are exact lowercase backend identifiers like candle, ndarray, flex, remote, or cubecl runtime names; hit in device.rs:289's `_ =>` arm.

Common situations: Typos in deployment scripts or Makefiles; using names from Burn's older APIs or other frameworks (e.g. 'cuda', 'cpu'); copying env config between projects that expose different backend names.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• BURN_DEVICE=flex requested, but the 'flex' feature is not en
• BURN_DEVICE=ndarray requested, but the 'ndarray' feature is
• capture tensor operations must run inside CaptureDevice::cap
• capture tensor {} has no initialized value
• seeding is not supported during graph capture

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