{"record":{"id":"3fa4848a30ce67f9","repo":"zeroclaw-labs/zeroclaw","slug":"uf2-at-does-not-look-like-a-valid-uf2-file-mag","errorCode":null,"errorMessage":"UF2 at {} does not look like a valid UF2 file (magic mismatch). Download from https://micropython.org/download/RPI_PICO/ and delete the existing file so ZeroClaw can re-extract it.","messagePattern":"UF2 at (.+?) does not look like a valid UF2 file \\(magic mismatch\\)\\. Download from https://micropython\\.org/download/RPI_PICO/ and delete the existing file so ZeroClaw can re-extract it\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-hardware/src/uf2.rs","lineNumber":103,"sourceCode":"// ── Flashing ──────────────────────────────────────────────────────────────────\n\npub async fn flash_uf2(mount_point: &Path, firmware_dir: &Path) -> Result<()> {\n    let uf2_src = firmware_dir.join(\"zeroclaw-pico.uf2\");\n    let uf2_dst = mount_point.join(\"firmware.uf2\");\n    let src_str = uf2_src.to_string_lossy().into_owned();\n    let dst_str = uf2_dst.to_string_lossy().into_owned();\n\n    ::zeroclaw_log::record!(\n        INFO,\n        ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Note)\n            .with_attrs(::serde_json::json!({\"src\": src_str, \"dst\": dst_str})),\n        \"flashing UF2\"\n    );\n\n    // Validate UF2 magic before any copy attempt — prevents flashing a stub.\n    let data = std::fs::read(&uf2_src)?;\n    if data.len() < 8 || data[..4] != UF2_MAGIC1 {\n        bail!(\n            \"UF2 at {} does not look like a valid UF2 file (magic mismatch). \\\n             Download from https://micropython.org/download/RPI_PICO/ and delete \\\n             the existing file so ZeroClaw can re-extract it.\",\n            uf2_src.display()\n        );\n    }\n\n    // ── Attempt 1: std::fs::copy (works on Linux, sometimes blocked on macOS) ─\n    {\n        let src = uf2_src.clone();\n        let dst = uf2_dst.clone();\n        let result = tokio::task::spawn_blocking(move || std::fs::copy(&src, &dst))\n            .await\n            .map_err(|e| {\n                ::zeroclaw_log::record!(\n                    ERROR,\n                    ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Fail)\n                        .with_outcome(::zeroclaw_log::EventOutcome::Failure)","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-hardware/src/uf2.rs#L85-L121","documentation":"Error \"UF2 at {} does not look like a valid UF2 file (magic mismatch). Download from https://micropython.org/download/RPI_PICO/ and delete the existing file so ZeroClaw can re-extract it.\" thrown in zeroclaw-labs/zeroclaw.","triggerScenarios":"Thrown at crates/zeroclaw-hardware/src/uf2.rs:103 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Download a valid UF2 from https://micropython.org/download/RPI_PICO/ and delete the existing corrupt file so ZeroClaw can re-extract it."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}