zeroclaw-labs/zeroclaw · error

Bundled UF2 is a placeholder — download the real MicroPython

Error message

Bundled UF2 is a placeholder — download the real MicroPython UF2 from https://micropython.org/download/RPI_PICO/ and place it at src/firmware/pico/zeroclaw-pico.uf2, then rebuild ZeroClaw.

What it means

Error "Bundled UF2 is a placeholder — download the real MicroPython UF2 from https://micropython.org/download/RPI_PICO/ and place it at src/firmware/pico/zeroclaw-pico.uf2, then rebuild ZeroClaw." thrown in zeroclaw-labs/zeroclaw.

Source

Thrown at crates/zeroclaw-hardware/src/uf2.rs:67

            ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)
                .with_outcome(::zeroclaw_log::EventOutcome::Failure),
            "cannot determine the user home directory"
        );
        anyhow::Error::msg("cannot determine home directory")
    })?;

    let firmware_dir = base
        .home_dir()
        .join(".zeroclaw")
        .join("firmware")
        .join("pico");
    std::fs::create_dir_all(&firmware_dir)?;

    // UF2 — validate magic before writing so a broken stub is caught early.
    let uf2_path = firmware_dir.join("zeroclaw-pico.uf2");
    if !uf2_path.exists() {
        if PICO_UF2.len() < 8 || PICO_UF2[..4] != UF2_MAGIC1 {
            bail!(
                "Bundled UF2 is a placeholder — download the real MicroPython UF2 from \
                 https://micropython.org/download/RPI_PICO/ and place it at \
                 src/firmware/pico/zeroclaw-pico.uf2, then rebuild ZeroClaw."
            );
        }
        std::fs::write(&uf2_path, PICO_UF2)?;
        ::zeroclaw_log::record!(
            INFO,
            ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Note)
                .with_attrs(::serde_json::json!({"path": uf2_path.display().to_string()})),
            "extracted bundled UF2"
        );
    }

    Ok(firmware_dir)
}

// ── Flashing ──────────────────────────────────────────────────────────────────

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Download the real MicroPython UF2 from https://micropython.org/download/RPI_PICO/, place it at src/firmware/pico/zeroclaw-pico.uf2, and rebuild ZeroClaw.

When it happens

Trigger: Thrown at crates/zeroclaw-hardware/src/uf2.rs:67 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/f644a7c7fd682194. Report an issue: GitHub.