OPENWRT IMAGE SAFETY · SYSUPGRADE

Do Not Force the Upgrade Until You Know Why the Image Check Failed

Image check failed can mean the image does not match the device, or that the current configuration cannot migrate safely. Save the complete validation output and identify the exact cause before starting another write.

Review the Safe Recovery Path View recovery checklist

Paid macOS app · View local pricing in the Mac App Store. Recovery checks run on your Mac, not on this page.

Browsing on your phone? Open this on your Mac later

Copy this link and send it to your Mac using your preferred method.

This is an image-compatibility decision page, not a force-flashing tutorial. Do not use sysupgrade -F unless current official release notes or the exact device page explicitly require it.

STOP BEFORE WRITING

The full validation output matters more than the final “Image check failed” line

The image may not match the device, or the old configuration may simply be unsafe to migrate. Save the full output and verify the target, profile, hardware revision, image type, and migration requirement first.

Image safety decision

This is a preparation checklist, not live device detection.

  • Full validation output The final line alone does not identify the real cause Stop first
  • Device identity Target, profile, model, hardware revision, and region match Confirm
  • Image and migration Image type, layout, and configuration-retention rules match Confirm
  • Official basis Only device pages or release notes authorize special steps Verify

Red must not be hidden by a force flag; amber requires evidence from the official device and release documentation.

QUICK ANSWER

Classify the failure before choosing the safe next step

  • Do not use sysupgrade -F just to dismiss an unexplained warning.
  • Save every validation line before and after Image check failed.
  • Match target, subtarget, profile, exact model, hardware revision, and region.
  • Separate a wrong image from an upgrade that requires clearing configuration.
  • Use a special flag or installer only when current official instructions require it.

IMAGE DECISION PROCESS

Move from the full error to the official device procedure

Do not use -F to collapse different failures into one result. Compatibility, configuration migration, and device-specific installation require separate decisions.

  1. Step 1

    Save the full error

    Record every line around Image check failed, the current release, exact model, and firmware filename.

  2. Step 2

    Match image identity

    Verify target, subtarget, profile, hardware revision, image type, size, and checksum.

  3. Step 3

    Confirm migration rules

    Separate “do not keep settings,” a special installer, and an incompatible image, then follow the official path.

  4. Step 4

    Choose the next step

    Use special flags only when officially documented; if access is lost, assess SSH, failsafe, Web, or TFTP in evidence order.

PLAIN-LANGUAGE TERMS

Terms you will see during recovery

Target / subtarget

The OpenWrt platform build for a processor family and board group. It must match the device.

Device profile

The device-specific image recipe and supported-device identity used during validation.

sysupgrade image

An image intended for an already-running OpenWrt system, not automatically for factory or bootloader recovery.

Clean upgrade

Installing without retaining old configuration when the official migration path requires a fresh setup.

SIX COMPATIBILITY CHECKS

A force flag cannot repair these underlying mismatches

1

Read the complete validation result

OpenWrt validates more than the filename. The output can identify incompatible device metadata, image format, size, device-tree identity, or configuration migration. The lines before Image check failed usually determine the next safe action.

2

Match target, profile, and hardware revision

Similar model names do not make firmware interchangeable. Verify the target and subtarget, device profile, exact model suffix, hardware revision, and sales region against the official image record.

3

Confirm the image type and integrity

Factory, sysupgrade, recovery, initramfs, and device-specific installer images serve different stages. Download from an official path, verify the checksum, and do not rename another model’s image to make an interface accept it.

4

Separate clean upgrade from forced compatibility

An official message to upgrade without keeping settings is not permission to force an incompatible image. Back up what is still accessible, then follow the documented clean-upgrade or migration path.

5

Why sysupgrade -F is not a universal fix

OpenWrt documents -F as an override for compatibility checks. It cannot correct the wrong target, hardware revision, image size, partition layout, or a missing device-specific installer. Use it only for the narrowly documented path that explains why the override is safe.

6

If access is lost after a flash

Check direct Ethernet, the documented management IP, a same-subnet temporary Mac IP, SSH, and model-supported failsafe before assuming a brick. Move to Web recovery or TFTP only when the exact device documentation identifies that route.

FINAL CHECK

Before starting any new write

  • The complete output around Image check failed is saved
  • Target, subtarget, and profile match the exact device
  • Hardware revision and region match the image documentation
  • Factory, sysupgrade, recovery, or other image type is correct
  • Configuration clearing or a special migration has been checked
  • Any special flag is backed by current official device or release notes

MACOS RECOVERY PREPARATION

Prepare recovery only after confirming the device actually needs TFTP

Router Recovery helps check Ethernet, a temporary static IP, user-selected firmware, and the local TFTP waiting state; it does not approve a forced flash.

Prepare the Recovery Environment View OpenWrt recovery paths

FAQ

OpenWrt image-check questions

Does Image check failed mean the firmware is corrupt?

Not necessarily. It can report a device mismatch, wrong image type, unsupported layout, damaged download, or configuration that cannot be preserved. Read the full validation output.

Is sysupgrade -F safe when OpenWrt suggests force?

Only when current official release notes or the exact device procedure explicitly explain that upgrade path. The flag bypasses checks; it does not repair an incompatible image.

Is upgrading without settings the same as using -F?

No. Clearing configuration can be a documented migration requirement for a correct image. Forcing compatibility overrides a different safety check.

Can Router Recovery bypass the image check?

No. It does not bypass OpenWrt validation. It can help prepare a Mac-side TFTP recovery environment only if the exact device later requires that recovery method.

NEXT STEP