Error codes | PersistKit 1.0.0 documentation

Every code PersistKit reports, what caused it, whether anything was changed, and what to do next.

How to read a failure#

csharp

var result = Persist.Save(class="tok-str">"score", 1500);

if (!result.Ok)
{
    Debug.LogWarning(result.Code);      // class="tok-str">"PK-STORAGE-001"
    Debug.LogWarning(result.Message);   // what happened, in one sentence
    Debug.LogWarning(result.NextStep);  // what to try next
}

Nothing is changed by a failure unless the code says otherwise, and no failure is ever thrown for an ordinary condition such as a full disk.

Storage and format#

Code	Cause	Changed anything?
`PK-STORAGE-001`	The save file could not be written	No: the previous file is still there
`PK-STORAGE-002`	The save file could not be read	No
`PK-FORMAT-001`	Not a PersistKit save, a newer container, or a protected save with no passphrase in this build	No
`PK-VERSION-001`	The save came from a newer build of the game	No: the file is left exactly as it was
`PK-INTEGRITY-001`	The file was changed or damaged after it was written	No: the damaged file is kept where it is

Types and values#

Code	Cause	Changed anything?
`PK-TYPE-001`	That kind of value cannot be stored, so nothing was saved	No
`PK-VALUE-001`	The saved value cannot be read as the type you asked for	No

References, objects and assets#

Code	Cause	Changed anything?
`PK-REF-001`	The object that save points at is not in the loaded scenes	No: your default is returned
`PK-REF-002`	That object has no identity, so it cannot be found again	No
`PK-REF-003`	More than one object claims the same identity	No: nothing is picked at random
`PK-REF-004`	That asset has no place in the registry	No: press Register this asset
`PK-REF-005`	This build cannot resolve that asset key (or the entry is empty)	No
`PK-REF-006`	One key names two assets, or one asset has two keys	No
`PK-REF-007`	That key cannot be made into a scene object, or the object was not made by `Persist.Spawn`	No

Scenes, objects and time away#

Code	What it means	Was anything changed?
`PK-SCENE-001`	A scene a save expects is not loaded, so its objects could not be restored	No: nothing is invented
`PK-SCENE-002`	An object a save expects is missing from the loaded scenes	No
`PK-SCENE-003`	An object's parent is missing, so it was restored at the top level instead	Yes: the object was restored, at the top level
`PK-SCENE-004`	That object is not followed by the scene tracker, so it cannot be restored	No
`PK-INSTANCE-001`	That instance was retired, so it is deliberately not created again	No: the save file is untouched
`PK-OFFLINE-001`	The device's clock is behind the last time this save was seen, so no time away is claimed	No
`PK-OFFLINE-002`	The note about when this save was last seen could not be read, so the time away is not known	No

PK-INSTANCE-001 is what retiring an object reports when a game asks for one the player destroyed for good.

Slots and recovery#

Code	Cause	Changed anything?
`PK-SLOT-001`	That slot name cannot be used	No
`PK-SLOT-002`	There is no slot with that name	No
`PK-SLOT-003`	A slot's description file could not be trusted	No: the data can still be loaded
`PK-SLOT-004`	That slot exists but holds no saved data	No
`PK-SLOT-005`	That would delete or replace saved data, and was not confirmed	No
`PK-SLOT-006`	A slot with that name already exists	No
`PK-RECOVERY-001`	There is no usable backup to go back to	No
`PK-RECOVERY-002`	The current file was missing, so a copy was used	No: the copy is still on disk

Cloud#

Code	Cause	Changed anything?
`PK-CLOUD-001`	No provider is set	No
`PK-CLOUD-002`	The cloud could not be reached	No
`PK-CLOUD-003`	The service refused (credentials, permission, quota)	No
`PK-CLOUD-004`	Both copies changed, so a choice is needed	No: neither copy is touched
`PK-CLOUD-005`	The transfer was cancelled	No
`PK-CLOUD-006`	There is nothing stored remotely under that name	No
`PK-CLOUD-007`	The download arrived but cannot be used	No: the local copy is kept
`PK-CLOUD-008`	The provider does not support that operation	No
`PK-CLOUD-009`	The transfer took too long and was stopped	No

Migration#

Code	Cause	Changed anything?
`PK-MIGRATION-001`	No migration is registered for a step in the walk	No: the save was not loaded
`PK-MIGRATION-002`	A migration step failed	No: the file is exactly as it was
`PK-MIGRATION-003`	The migrations produced something this build cannot read	No: nothing was committed
`PK-MIGRATION-004`	The migrated file could not be written	The previous file was put back

Seeing it in one place#

Tools → PersistKit → Diagnostics (and Persist.Diagnostics.Report()) gathers the versions, the save folder, every slot's state and size, and the last problem — read from disk when the report is built, so a file that changed behind PersistKit's back cannot be hidden by anything remembered.