docs-internal/engine/ACTOR_KV.md
Each actor has its own private KV store which can be manipulated or accessed with the engine KV operations.
For current RivetKit actors, runtime persistence no longer uses this store directly. State, connections, queues, workflow storage, alarms, and deprecated user c.kv data live in internal SQLite tables after the first wake on the migrated runtime. Legacy actor KV data remains as a frozen downgrade snapshot, and the inspector token is mirrored to KV for dashboard compatibility.
The first-wake import fails closed if a legacy queue record contains retry, delay, or in-flight delivery metadata. The SQLite queue model cannot preserve those fields, so silently importing or dropping them would change delivery semantics. The startup error identifies the record; operators must inspect and resolve that legacy queue entry before retrying the actor.
A KV key is a byte array, aka a blob. A KV value is also a byte array/blob.
Every set KV value contains metadata which includes the version and create timestamp of the key (version being a string byte array denoting the version of the Rivet Engine).
Keys that don't exist aren't included in the output so it is important to read the output's list of keys.
This operation deletes all keys in the entire actor's KV store. Use cautiously.
Every operation can return an error instead of its regular response. The error includes a message string.
Each KV request has a u32 request ID which is to be provided by the user (handled internally by RivetKit). Rivet makes no attempt to order or deduplicate the responses to KV requests, it is up to the client to match the responses to the requests via the request ID.