OpenWrt flash safety
Do not force the upgrade until you know why the image check failed
An OpenWrt image check failure can point to the wrong target, profile, hardware revision, image type, partition layout, or an upgrade that must not preserve configuration. The complete error and the exact device instructions matter.
Stop before using sysupgrade -F. Unless the official release notes or the exact device page explicitly require the force flag for your model and upgrade path, do not use it to dismiss an image warning. It overrides compatibility checks; it cannot turn the wrong firmware into the right firmware.
This is a decision guide, not a force-flashing tutorial. Keep power connected, save the complete error, and do not start another write until you have identified the reason for the failed check.
1. What “Image check failed” actually means
OpenWrt validates more than a filename. Depending on the device and release, the check may examine image metadata, signature, supported-device identity, device-tree compatibility, image size, and whether the saved configuration can migrate safely.
Read the lines before and after the message. A request to upgrade without keeping settings is different from a rejected device image, an unsupported layout transition, or a damaged download.
2. Match every part of the firmware identity
| Check | Why it matters |
|---|---|
| Target and subtarget | They identify the processor family and platform build. Similar product names do not make images interchangeable. |
| Device profile | The profile carries the device-specific support and image recipe. |
| Hardware revision | V1, V2, regional variants, and similarly named models may use different flash layouts or components. |
| Image type | factory, sysupgrade, initramfs, and vendor recovery images serve different installation stages. |
| Partition layout and image size | A release can change layout or impose a model-specific maximum size. A forced write does not repair that mismatch. |
Re-download the image from the official Firmware Selector or release path and verify its checksum. Do not rename a different model's image just to make a recovery interface accept it.
3. Some upgrades must clear configuration
An image can be correct while the old configuration is unsafe to preserve. OpenWrt's current release notes include devices and targets that require a clean upgrade, a factory reinstall, or a special installer. Examples include the ipq806x transition in 24.10.7, BPI-R4 configuration handling in 25.12.5, and separate migration procedures for devices such as the Linksys E8450 / Belkin RT3200.
4. Why -F is not a universal fix
OpenWrt documents -F as an override for compatibility checks. That can be legitimate only when an official, device-specific procedure explicitly calls for it. OpenWrt 25.12.5, for example, gives narrowly scoped force-upgrade instructions for certain TP-Link RE355 and RE450 upgrade paths.
The flag cannot correct a wrong target, wrong hardware revision, oversized image, incompatible partition map, or a device that needs an installer or vendor recovery flow. If the official instructions do not explain why the override is safe, stop and verify instead.
5. If the router is unreachable after a flash
Do not repeatedly upload different images while guessing. Preserve any access you still have and identify the bootloader or recovery mechanism first.
6. What Router Recovery can—and cannot—do
Router Recovery can help prepare a local macOS TFTP Server recovery environment: direct Ethernet, a temporary static IP, the user-selected firmware folder and filename, and recovery-mode checks.
It cannot decide that an incompatible OpenWrt image is safe, bypass OpenWrt validation, rewrite partition layouts, perform device-specific installers, or guarantee that a router will recover. Recovery depends on the exact model, hardware revision, trusted firmware, and documented bootloader path.
Official references checked
Verified July 18, 2026: OpenWrt sysupgrade technical reference, OpenWrt owut/sysupgrade guide, OpenWrt 25.12.5 release notes, and OpenWrt 24.10.7 release notes.
Release notes change as issues are discovered. Recheck the current notes and the exact device page before flashing.