ATFS-BAD-IDENTITY-KEY

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

atfs refused to start because ATFS_IDENTITY_KEY is set to a value it cannot decode. This variable is normally left empty. Setting it hands an instance a specific libp2p identity in advance.

What triggered it

When set, ATFS_IDENTITY_KEY must be a base64-encoded libp2p private key. atfs uses it to derive the instance’s peer ID, the identity other nodes and the DHT know it by. A value that fails to decode, or that decodes to something other than a valid private key, fails this check.

Why this matters

A peer ID is not cosmetic. It is half of the instance’s dev.atfs.server record address: at://{owner-did}/dev.atfs.server/{peer-id}. If atfs silently generated a fresh identity instead of honoring a broken key, the instance would start under a peer ID no existing record names, unreachable at the address anyone already has for it. Refusing to start is safer than starting under an identity nobody is looking for.

Fix

Correct ATFS_IDENTITY_KEY, or remove it entirely. Removing it lets atfs generate its own identity on first run. See the settings reference for the field’s format.

Common pitfalls

• Copying the key with surrounding quotes or a trailing newline, which corrupts the base64 encoding.
• Pasting a public key or a peer ID by mistake, instead of the base64-encoded private key atfs expects.
• Restoring a key recovered from another device without first confirming it is the exact key that device’s own record’s rkey names. A wrong key can still decode successfully, and only fails later, once the peer ID it produces does not match any record.

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