What causes "compile with '--features flash-attn'" in huggingface/candle?

Rebuild with `cargo build --release --features candle-transformers/flash-attn` (CUDA required).

compile with '--features flash-attn'

Error message

compile with '--features flash-attn'

What it means

In mimi/transformer.rs the `flash_attn` helper's fallback (no `flash-attn` feature) panics with `unimplemented!`. The Mimi transformer attention calls this helper when flash attention is selected, so the missing feature turns into a runtime panic.

Source

Thrown at candle-transformers/src/models/mimi/transformer.rs:776

            }
        })
    }
}

#[cfg(feature = "flash-attn")]
fn flash_attn(
    q: &Tensor,
    k: &Tensor,
    v: &Tensor,
    softmax_scale: f32,
    causal: bool,
) -> Result<Tensor> {
    candle_flash_attn::flash_attn(q, k, v, softmax_scale, causal)
}

#[cfg(not(feature = "flash-attn"))]
fn flash_attn(_: &Tensor, _: &Tensor, _: &Tensor, _: f32, _: bool) -> Result<Tensor> {
    unimplemented!("compile with '--features flash-attn'")
}

View on GitHub (pinned to d5fee525bf)

Solutions

Rebuild with `cargo build --release --features candle-transformers/flash-attn` (CUDA required).
Disable flash attention in the Mimi config so the standard attention path is used.
If not applicable (Mimi defaults may not set it), check code that toggles the flash flag before constructing the transformer.

Example fix

// before
cargo run --release --example mimi-demo
// after
cargo run --release --features candle-transformers/flash-attn --example mimi-demo

Defensive patterns

Strategy: validation

Validate before calling

#[cfg(not(feature = "flash-attn"))]
fn ensure_no_flash(cfg_use_flash: bool) {
    assert!(!cfg_use_flash, "mimi: flash-attn requires --features candle-transformers/flash-attn");
}

Type guard

fn can_flash(use_flash: bool) -> bool {
    !use_flash || cfg!(feature = "flash-attn")
}

Try / catch

if !can_flash(config.transformer.use_flash_attn) {
    config.transformer.use_flash_attn = false;
}

Prevention

Validate nested config sections (transformer) for flash flags too
Enable the feature only on CUDA-capable CI runners
Keep audio codec examples buildable without the feature
Log when silently downgrading to standard attention

When it happens

Trigger: Running the Mimi audio codec model with flash attention enabled in its transformer config while compiled without `--features flash-attn`.

Common situations: Weights/config enabling flash attention; default cargo builds; running on CPU/macOS hosts where the CUDA-only flash-attn kernel is unavailable.

Related errors

AI-assisted analysis of huggingface/candle@d5fee525bf (2026-09-02). Data as JSON: /api/errors/f886e112a1a93b22. Report an issue: GitHub.