{"record":{"id":"da1ece7acebbd5cc","repo":"nautechsystems/nautilus_trader","slug":"cannot-increment-time-while-clock-is-in-realtime-m","errorCode":null,"errorMessage":"Cannot increment time while clock is in realtime mode","messagePattern":"Cannot increment time while clock is in realtime mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/core/src/time.rs","lineNumber":281,"sourceCode":"    /// Increments the current static-mode time by `delta` and returns the updated value.\n    ///\n    /// Internally this uses [`AtomicU64::try_update`] with [`Ordering::AcqRel`] to ensure the increment is\n    /// atomic and visible to readers using `Acquire` loads.\n    ///\n    /// # Errors\n    ///\n    /// Returns an error if the increment would overflow `u64::MAX` or if called\n    /// while the clock is in real-time mode.\n    ///\n    /// # Thread Safety\n    ///\n    /// The mode check is not atomic with the subsequent update. If another thread calls\n    /// `make_realtime()` between the check and update, the invariant can be violated.\n    /// This is intentional: mode switching is a setup-time operation and should not\n    /// occur concurrently with time operations. Callers must ensure mode switches are\n    /// complete before resuming time operations.\n    pub fn increment_time(&self, delta: DurationNanos) -> anyhow::Result<UnixNanos> {\n        anyhow::ensure!(\n            !self.realtime.load(Ordering::SeqCst),\n            \"Cannot increment time while clock is in realtime mode\"\n        );\n\n        let previous =\n            match self\n                .timestamp_ns\n                .try_update(Ordering::AcqRel, Ordering::Acquire, |current| {\n                    current.checked_add(delta.as_u64())\n                }) {\n                Ok(prev) => prev,\n                Err(_) => anyhow::bail!(\"Cannot increment time beyond u64::MAX\"),\n            };\n\n        debug_assert!(\n            !self.realtime.load(Ordering::SeqCst),\n            \"Invariant: clock must remain in static mode across `increment_time`\"\n        );","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/core/src/time.rs#L263-L299","documentation":"increment_time advances the TestClock's internal time, which is only meaningful when the clock is static (test/backtest mode). If the clock is in realtime mode, mutating time manually would violate the clock's invariants, so the operation is rejected with this error. The check is intentionally non-atomic: mode switches must be completed before time operations.","triggerScenarios":"Calling clock.increment_time(delta) after clock.set_realtime(...) / make_realtime() without switching back to static mode. Typical in tests or live-node code that reuses a TestClock instance that was switched to realtime.","commonSituations":"Unit tests that flip a clock to realtime mid-test then try to fast-forward; backtest engines accidentally running with a realtime-mode clock; shared clock objects whose mode was changed elsewhere.","solutions":["Call the clock's make_static/set_static equivalent before increment_time.","Use a dedicated TestClock instance for time control and never switch it to realtime in the same test.","Restructure the code so realtime clocks never receive manual time increments."],"exampleFix":"// before\nclock.set_realtime();\nclock.increment_time(delta)?; // errors\n// after\nclock.make_static();\nclock.increment_time(delta)?;","handlingStrategy":"type-guard","validationCode":"// guard before mutating\nif clock.is_realtime() { return Err(anyhow::anyhow!(\"clock is realtime; cannot increment\")); }","typeGuard":"fn is_static(clock: &TestClock) -> bool { !clock.realtime.load(Ordering::SeqCst) } // conceptually; use the public accessor","tryCatchPattern":"clock.make_static();\nclock.increment_time(delta)\n    .context(\"failed to advance test clock\")?;","preventionTips":["Complete all mode switches before performing time operations on a clock.","Use a dedicated TestClock per test and never flip it to realtime when testing time-based logic.","Keep realtime and test clocks as separate instances in shared infrastructure."],"tags":["clock","rust","invalid-state"],"backgroundTag":"invalid-state-transition","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"}