ATFS-DATA-READONLY

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

atfs refused to start because it could not write to its own data directory. A startup write test failed, which usually means the underlying filesystem has gone read-only.

What triggered it

Before doing anything else, atfs writes a small test file to ATFS_DATA_DIR and confirms it can read it back. On this instance, that write failed. The most common cause is a filesystem the kernel has already remounted read-only, after detecting corruption it cannot repair on its own.

Why this matters

Every piece of atfs’s durable state — blobs, the UnixFS index, the libp2p identity key — lives under this one directory. An instance that cannot write here cannot serve new uploads, cannot persist pin intents, and cannot even confirm its own identity key is intact. Running anyway, in a half-functional state that looks live but silently drops data, would be worse than refusing to start.

Fix

Reflash or reformat the data volume, or point ATFS_DATA_DIR at a different, writable location. On an SD-card device, check the serial console’s boot log first. A remount to read-only is usually logged there, with the specific filesystem error that caused it. See Read the report for how to reach that log.

Common pitfalls

• Restarting the device without addressing the underlying filesystem problem. A remount-to-read-only event usually recurs on the same damaged volume.
• Treating this as a permissions problem. A read-only remount is a filesystem-health event, not something a chmod fixes.
• Assuming this code only happens on SD-card hardware. A Docker volume backed by a failing disk, or mounted read-only by mistake, fails the same write test.

See the settings reference for ATFS_DATA_DIR and its platform-specific defaults.