{"record":{"id":"b46ff45d0be6cc84","repo":"nautechsystems/nautilus_trader","slug":"failed-to-restore-actor-actor-id-state-e","errorCode":null,"errorMessage":"Failed to restore actor {actor_id} state: {e:#}","messagePattern":"Failed to restore actor (.+?) state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/system/src/trader.rs","lineNumber":1591,"sourceCode":"\n            (trader.cache.clone(), actor_callbacks, strategy_callbacks)\n        };\n\n        if !cache.borrow().has_backing() {\n            return Ok(());\n        }\n\n        for (actor_id, callbacks) in actor_callbacks {\n            let state = cache\n                .borrow()\n                .load_actor_state(&actor_id)\n                .map_err(|e| anyhow::anyhow!(\"Failed to load actor {actor_id} state: {e:#}\"))?;\n            let Some(state) = state.filter(|state| !state.is_empty()) else {\n                continue;\n            };\n\n            (callbacks.load)(actor_id.inner(), state)\n                .map_err(|e| anyhow::anyhow!(\"Failed to restore actor {actor_id} state: {e:#}\"))?;\n        }\n\n        for (strategy_id, callbacks) in strategy_callbacks {\n            let state = cache\n                .borrow()\n                .load_strategy_state(&strategy_id)\n                .map_err(|e| {\n                    anyhow::anyhow!(\"Failed to load strategy {strategy_id} state: {e:#}\")\n                })?;\n            let Some(state) = state.filter(|state| !state.is_empty()) else {\n                continue;\n            };\n\n            (callbacks.load)(strategy_id.inner(), state).map_err(|e| {\n                anyhow::anyhow!(\"Failed to restore strategy {strategy_id} state: {e:#}\")\n            })?;\n        }\n","sourceCodeStart":1573,"sourceCodeEnd":1609,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/system/src/trader.rs#L1573-L1609","documentation":"Raised in `Trader::load_state` when an actor's registered `on_load` state-restoration callback itself returns an error. The state was successfully read from the cache, but the actor rejected restoring it (invalid/ incompatible payload), so state recovery aborts with this message.","triggerScenarios":"Calling trader start with state recovery enabled; the cache returns a non-empty `PersistedComponentState` for an actor, and the actor's `load` callback errors — e.g. the payload was saved by a different actor type/version or fails deserialization into the actor's internal state type.","commonSituations":"Upgrading nautilus and restarting with state persisted by the previous version; changing an actor's saved-state struct fields without a migration; pointing the node at a cache containing state from a different strategy/actor configuration.","solutions":["Inspect the wrapped `{e:#}` to see why the actor rejected the state and fix the deserialization/schema mismatch","Ensure the same actor implementation and state schema that saved the state also restores it, or add a migration in the load callback","Clear the actor's stale persisted state in the cache if it is no longer compatible, and re-run to save fresh state","Pin/cache-compatible library versions across node restarts"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// verify state round-trips before restart\nlet state = cache.load_actor_state(&actor_id)?;\nactor.test_restore(state.clone())?;","typeGuard":null,"tryCatchPattern":"do {\n    system.start_with_recovery()\n} catch e if e.contains(\"Failed to restore actor\") => {\n    // clear the incompatible persisted state or migrate schema, then restart\n}","preventionTips":["Keep actor state structs backward-compatible or add migration in the load callback","Save and restore state with the same actor implementation and library version","Test state save/restore round-trips in CI before deploying upgrades","Clear stale persisted state when deliberately changing an actor's schema"],"tags":["state","actor","restore","persistence"],"backgroundTag":"state-restore-failed","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}