Error codes | NexusForge Persistence 0.2.0 documentation

The stable NF.PERSIST codes, grouped by subsystem, with the fix that belongs to each one.

Why codes, not messages#

Codes are stable strings and messages are for humans. Branch on the code; show the message. Every expected failure arrives as a PersistenceResult, so a code is a value you can handle rather than a stack trace you have to parse.

Storage and slots#

Code	Meaning	Fix
`NF.PERSIST.STORAGE.NOT_FOUND`	The slot was never written	Treat `LoadOutcome.NotFound` as "new game", not as an error
`NF.PERSIST.STORAGE.PATH_TOO_LONG`	Namespace + environment + slot exceeded the path budget	Shorten the namespace, or raise `Storage.MaxPathLength` deliberately
`NF.PERSIST.STORAGE.WRITE_FAILED`	The platform refused the write	Check free space, permissions and whether another process holds the file
`NF.PERSIST.SLOT.NOT_FOUND`	The named slot does not exist	Same as above: it is an outcome, not an incident

Lifecycle#

Code	Meaning	Fix
`NF.PERSIST.LIFECYCLE.NOT_INITIALIZED`	A save was attempted before `Initialize`	Call `Initialize` during startup
`NF.PERSIST.LIFECYCLE.INIT_REJECTED`	A second initialisation was refused; the new host was discarded	Call `ResetForNewSession()` first if you intend to replace the running host

Envelope, serialization and migration#

Code	Meaning	Fix
`NF.PERSIST.ENVELOPE.INTEGRITY_MISMATCH`	The file is damaged	Use recovery — the framework restores the newest valid backup
`NF.PERSIST.SERIALIZATION.MALFORMED`	The document does not match the model	Usually a model change without a migration, or a member the type cannot represent
`NF.PERSIST.MIGRATION.PATH_MISSING`	A migration step is missing for a schema in the save	Register the step, and declare the versions so validation catches it first

Security#

Code	Meaning	Fix
`NF.PERSIST.SECURITY.KEY_UNAVAILABLE`	Encryption or authentication is configured and no key was supplied	Register an `ISaveKeyProvider`, or turn encryption off
`NF.PERSIST.SECURITY.AUTHENTICATION_FAILED`	The file was altered, or not written with the supplied key	Check the key provider and `Security.KeyId`; nothing was read or decrypted

Next#

Troubleshooting — the same problems in the order people meet them.
Result types — how a code reaches your code.
Diagnostics — the event codes logged beside these failures.