ATFS-EMMC-UNHEALTHY

Fully documented: why this happens, and how to fix it.

This page only applies when you deploy to an SD-card device.

atfs refused to start because its own eMMC volume exists but will not mount. This differs from ATFS-EMMC-FOREIGN: the eMMC here is atfs’s own data, damaged rather than foreign.

What triggered it

atfs recognized the eMMC’s volume as one it created, by its filesystem label. But when atfs tried to mount it, the mount itself failed. That points to filesystem corruption or hardware wear, not a foreign disk atfs should leave alone.

Why this matters

atfs deliberately distinguishes “not mine” from “mine, but broken.” Foreign content demands explicit authorization before atfs touches it at all, since somebody else’s data might still be recoverable. Content that is already atfs’s own, and already unmountable, is a different decision: recovery may not be possible, but rebuilding it is atfs’s call to make, once an operator authorizes it, since no third party’s data is at risk.

Fix

Choose one of two paths.

• Set ATFS_DATA_DIR to the SD card’s data partition instead, and leave the eMMC untouched. This preserves whatever might still be recoverable from it later, by other means.
• Authorize a rebuild by setting ATFS_FORMAT_DRIVES_IF_NOT_ATFS to today’s UTC date.

See the settings reference for both variables.

Common pitfalls

• Authorizing a rebuild before checking whether the SD-card fallback would serve just as well. A rebuild is not reversible; switching ATFS_DATA_DIR is.
• Forgetting that a rebuilt instance needs a new dev.atfs.server record, at its new peer ID, before uploads or follows work again. The old record, whose rkey names the old peer ID, is orphaned.
• Treating this the same as ATFS-EMMC-FOREIGN. That code’s wipe destroys someone else’s content; this rebuild destroys atfs’s own, already unhealthy content, plus the libp2p identity key.

See Read the report for how to find this code in the first place, on whichever platform your instance runs.