UBI Attachment Fails After a Flash Change: Compare Geometry Before Rebuilding the Filesystem
When UBI attachment fails after a flash change, compare the target’s physical geometry and expected header offsets with the image’s recorded layout before rebuilding anything. A valid image for the old geometry can be incompatible with the new attachment configuration. Reformatting first destroys the evidence needed to distinguish that mismatch from damaged data.
This diagnostic path is pinned to Linux v6.12 UBI and UBIFS. Image-generation tools and vendor kernels must be checked at their own versions. No erase, format, or repair commands are supplied. Begin with existing logs, build manifests, and preserved image copies; attaching UBI or mounting a filesystem is not automatically a passive forensic read.
1. Locate the failing layer
Linux 6.12 UBIFS documentation places UBIFS on a UBI volume, while UBI manages the underlying MTD storage. Failure to attach the MTD device to UBI precedes mounting UBIFS. Keep the first UBI error instead of diagnosing only the later “root filesystem unavailable” symptom.
Record the selected MTD identity, partition offset and length, NAND part, controller, effective ECC mode, kernel revision, boot arguments, and previous known-good configuration. Device numbering can change with a new partition map. Confirm the named target rather than assuming that the same numeric index still selects the same bytes.
| Failure stage | Primary evidence | First question |
|---|---|---|
| Underlying MTD reads. | Read errors, ECC reports, identification, and repeated-read consistency. | Can the image bytes be acquired reliably through this configuration? |
| UBI header interpretation. | EC/VID header messages, offsets, CRC results, and image identity. | Does the stored UBI layout match attachment expectations? |
| UBI volume availability. | Volume identity, type, and usable logical geometry. | Is the intended volume present and usable? |
| UBIFS superblock validation. | Filesystem minimum-I/O and logical-eraseblock checks. | Does the filesystem image match the volume it is being mounted on? |
2. Compare the two geometry records
Make one column for the image-generation contract and one for the actual target. Include physical eraseblock size, minimum data I/O size, header/subpage write granularity, VID-header offset, data offset, resulting logical eraseblock size, volume alignment, and selected partition boundaries. Do not fill missing image-generation values from today’s target and assume they were always the same.
The v6.12 UBI media format stores VID-header and data offsets in the erase-counter header, relative to the beginning of a physical eraseblock. The attachment implementation derives its layout from the MTD geometry and configured offset, aligns the data start, and computes logical eraseblock size as physical eraseblock size minus data start.
Keep subpage capability explicit. A replacement, controller change, or driver change can alter the effective header-write granularity without changing the marketed total capacity. Do not restore an old VID offset unless the new path actually supports the resulting layout.
Also identify the artifact type. A UBI image containing volume metadata, a UBIFS filesystem image intended for a volume, and a physical NAND dump with spare bytes are different objects. Record which object the manufacturing tool expects and whether it inserts ECC, skips bad blocks, or transforms the layout. A filename suffix is weaker evidence than the build recipe and verified format.
3. Interpret a mismatch instead of patching around it
The v6.12 UBI I/O code explicitly checks stored VID-header and data offsets against the expected values. A mismatch points to an image/configuration disagreement; it does not establish that the filesystem payload itself is corrupt.
On a preserved copy, inspect several valid erase-counter headers and retain their CRC results. One plausible header from an arbitrary location is not enough. Mixed image generations, a wrong partition base, truncated programming, and unreliable reads can produce different failure patterns that deserve separate findings.
Do not edit header bytes and recalculate a checksum merely to silence the error. Moving the declared data offset without moving the data changes the meaning of the image. A successful checksum after a manual patch proves only that the modified header is self-consistent under that checksum.
If UBI attaches successfully but UBIFS then reports a size mismatch, move up one layer. The v6.12 UBIFS superblock validator checks stored minimum-I/O and LEB sizes against the actual volume. Repeating UBI attachment with unrelated parameters is not a substitute for reconciling that filesystem-image contract.
4. Use a parameter-change example
Consider a hypothetical 131,072-byte physical eraseblock. An image whose data starts at byte 2,048 exposes a base UBI LEB size of 129,024 bytes. If the target instead derives a 4,096-byte data start, its base LEB size becomes 126,976 bytes. Equal physical capacity has not preserved the logical geometry.
Those values are illustrative arithmetic, not a recommended layout or a claim about a particular NAND. Volume alignment can impose an additional usable-size constraint. The useful conclusion is that the image and target must agree on the actual offsets and exposed volume geometry, not merely on the eraseblock’s total byte count.
5. Choose the next action from preserved evidence
| Finding | Appropriate next action |
|---|---|
| Wrong partition or device selected. | Correct target selection in a controlled configuration and verify against the preserved layout. |
| Valid old image, supported old geometry, incorrect new attachment configuration. | Qualify a configuration correction on a copy or disposable test media. |
| New media cannot support the old image layout. | Plan supported extraction and image regeneration for the new geometry, preserving original data. |
| Inconsistent headers or acquisition errors. | Resolve read-path or partial-programming evidence before classifying filesystem damage. |
| UBI succeeds; UBIFS geometry fails. | Reconcile the filesystem build parameters with the actual volume contract. |
Before any write-based qualification, retain a verified backup, per-unit data and factory-marker evidence, and a recovery route. Use approved test hardware with no irreplaceable contents. A successful blank-media experiment proves that the new stack can create a volume; it does not prove that the original image was safely migrated.
Close the incident with a reproducible comparison
Keep the original failure log, two-column geometry worksheet, image hash, exact image-generation recipe, target configuration, and the first successful controlled result. Validate extracted application data as well as filesystem accessibility. Calibration from the wrong unit remains wrong even if every file opens.
A hypothetical flash substitution that changes header-write granularity should end with a documented compatible image/configuration pair or an explicit migration hold. It should not end with “formatting fixed it” while the reason for the original incompatibility and the fate of persistent data remain unknown.
