ATFS-EMMC-FOREIGN

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 the board’s onboard eMMC already holds a filesystem or data atfs did not create. It left the drive untouched rather than guess what to do with it.

What triggered it

On an SBC with onboard eMMC, atfs formats a fresh eMMC automatically on first boot, and uses it as ATFS_DATA_DIR by default. Before formatting anything, atfs checks whether the eMMC already carries content. Finding a filesystem or data that is not atfs’s own — a previous OS install, a different appliance’s data, or a manual write — atfs stops rather than overwrite it.

Why this matters

An automatic default that quietly wipes a drive is a serious hazard the moment that drive might hold something valuable. This check exists specifically for boards resold, repurposed, or dual-booted before atfs ever ran on them. Overwriting foreign content without explicit authorization would be a silent, unrecoverable loss of somebody else’s data — exactly the failure mode a bare-minimum appliance must never produce by default.

Fix

Choose one of two paths.

• Authorize a wipe by setting ATFS_FORMAT_DRIVES_IF_NOT_ATFS to today’s UTC date, in YYYY-MM-DD form.
• Opt out of eMMC storage entirely by setting ATFS_DATA_DIR to the SD card’s own data partition instead.

See the settings reference for both variables.

Common pitfalls

• Setting ATFS_FORMAT_DRIVES_IF_NOT_ATFS to true or yes. atfs requires today’s actual date, not a boolean, precisely so the authorization cannot be baked into an image and forgotten.
• Setting yesterday’s or tomorrow’s date. The date must match the current UTC date at boot time.
• Assuming this check only fires once. It runs on every boot, until the eMMC either holds atfs’s own volume or ATFS_DATA_DIR points elsewhere.

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