LittleFS(mount=True) on a fresh buffer produces a different on-disk image than explicit format()+mount() — fails on some embedded targets

[Jason2866]

Summary

LittleFS(..., mount=True) does not produce the same on-disk image as LittleFS(..., mount=False) followed by explicit fs.format() + fs.mount() when the backing buffer is uninitialized. The two paths produce different superblock revision counts in the first 4 bytes of the image, and on some embedded targets the constructor-built image fails to mount.

Affected code

src/littlefs/__init__.py lines 61–70:

def __init__(self, context: Optional["UserContext"] = None, mount=True, **kwargs) -> None:
    self.cfg = lfs.LFSConfig(context=context, **kwargs)
    self.fs = lfs.LFSFilesystem()

    if mount:
        try:
            self.mount()           # ① reads garbage, fails
        except errors.LittleFSError:
            self.format()          # ② runs on a now-dirty lfs_t
            self.mount()           # ③

Root cause

When the backing buffer is fresh (no valid superblock):

1. self.mount() is called on a pristine lfs_t. Internally lfs_mount() reads block 0/1, scans the lookahead buffer, and mutates the lfs_t C struct (allocator state, seed, cached revision counters) before raising LittleFSError.
2. self.format() then runs on that dirty lfs_t. The superblock it writes is influenced by the leftover state from the failed mount — most visibly, the revision counter in the first 4 bytes of the superblock is not the expected 0x00000001.
3. The resulting image still mounts successfully inside the same Python process (because the in-memory state is consistent), but a fresh LittleFS driver — e.g. on an embedded target reading the same bytes from flash — sees a superblock that does not match what a clean format() would have produced and refuses to mount.

The contrasting code path, LittleFS(mount=False) followed by explicit fs.format() + fs.mount(), runs lfs_format() on a pristine lfs_t and produces a superblock that mounts on-device.

Reproduction / evidence

Reported and reproduced on ESP8684 (XH-C2X) in pioarduino/platform-espressif32:

• Image built with LittleFS(mount=True) (first 32 bytes):
  01000000 F00FFFF7 6C6974746C656673 2FE0001000000200 0010000060010000
  → fails to mount on device.
• Image built with LittleFS(mount=False) + explicit format() + mount() (first 32 bytes):
  F6010000 F00FFFF7 6C6974746C656673 2FE0001000000200 0010000060010000
  → mounts successfully on device.

The "littlefs" magic at offset 8 and everything after is identical; only the revision count in bytes 0–3 differs, and only the second image is accepted by the device-side LittleFS driver.

Original downstream issue and discussion:
Jason2866/platform-espressif32#237 (see comment 4391264360).

Workaround (already applied downstream)

fs = LittleFS(..., mount=False)
fs.format()
fs.mount()

Suggested fix in littlefs-python

Re-create the lfs_t between the failed mount and the subsequent format so lfs_format() always sees a pristine struct:

if mount:
    try:
        self.mount()
    except errors.LittleFSError:
        self.fs = lfs.LFSFilesystem()  # reset C struct
        self.format()
        self.mount()

This would make mount=True produce the same on-disk image as the explicit-format workaround, and avoid surprising downstream users who build images for embedded targets.

Environment

• littlefs-python: latest from PyPI / main
• Python: 3.11
• Downstream consumer: pioarduino/platform-espressif32 image builder
• Affected device: ESP8684 / XH-C2X (LittleFS on ESP-IDF), reported by @msantos2007

[BrianPugh]

I can't seem to reproduce the issue (on macos). Are you sure this is the cause of the issue you are observing?

[Jason2866]

Yes, reproduced on macos and solved with the explicit format not trying automount. It does not happen always! The failed mount seems to leave a more or random state.

[BrianPugh]

Spent some time on this and was able to reproduce the original issue. See attached issue-167.py.

I don't believe the explanation in the original post is correct. What's going on (block_cycles=500):

• fresh 0xFF buffer: both paths produce identical bytes, rev=1. Issue doesn't repro.
• buffer that already contains a valid littlefs image: constructor's mount() succeeds (it's a valid fs), so format() is never called and you get whatever the prior format wrote, rev=1. Explicit format() re-formats, reads existing rev=1, aligns up to (block_cycles+1)|1=501, commits, rev=502. That's the entire delta.

So mount() doesn't fail in the broken case, there's no dirty lfs_t, and resetting it does nothing. I tried the proposed patch in the repro, and the resulting binaries are identical.

The committed fix in Jason2866/platform-espressif32 sets mount=False and then calls format() + mount(). That produces rev=1, byte-identical to the original "broken" code. The rev=502 image that was validated on hardware came from the snippet in the earlier comment which "removed mount=True" but mount=True is the default, so the constructor still auto-formatted and then your explicit format() ran a second time. Accidental double-format. The committed fix doesn't do that.

Three variants from my script, fresh buffer:

A: LittleFS(mount=True)                       rev=1     (current pioarduino code)
B: LittleFS() + format()                      rev=502   (your comment, accidental 2x format)
C: LittleFS(mount=False) + format() + mount() rev=1     (your committed fix, identical to A)

All that said, i don't understand why one of these would boot properly on the device and the other one wouldn't.
Would you mind re-flashing and testing the ESP8684 with the bytes your Arduino/IDF55_gcc152 branch produces?

Either way I don't think this is actually a littlefs-python bug (but am open to more evidence!).

issue-167.py