nautechsystems/nautilus_trader · error

Cannot add actor while node is running, add actors before…

Error message

Cannot add actor while node is running, add actors before running the node

What it means

Lifecycle guard in add_actor: components must be registered before the node runs; once the node is running the trader's message routing is live and adding an actor would bypass its start sequence, so the call bails.

Solutions

1. Register all actors before calling run/start on the node
2. If dynamic composition is needed, create a separate node instance or defer to the appropriate engine API designed for runtime changes
3. Guard with a state check: only call add_actor when node.state() == NodeState::Idle

Example fix

// before
node.run().await?;
node.add_actor(my_actor)?;
// after
node.add_actor(my_actor)?;
node.run().await?;

if node.state() == NodeState::Idle {
    node.add_actor(actor)?;
}

When it happens

Trigger: Calling node.add_actor(actor) when node.state() != NodeState::Idle — i.e. after start/run was invoked or during startup/running phases.

Common situations: Dynamically adding actors in response to runtime events; setup code accidentally executed after run(); test helpers (e.g. test_add_actor_registers_constructed_instance) calling add_actor on a node already progressed past Idle.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Cannot add strategy while node is running, add strategies…
• Cannot set cache database while node is running, set it…
• Already running
• DataActor must be registered before accessing cache
• DataActor must be registered before accessing clock

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/77ff0506b52aa61e. Report an issue: GitHub.

Appendix: source

Thrown at crates/live/src/node/mod.rs:2643

    /// Adds an actor to the trader.
    ///
    /// This method provides a high-level interface for adding actors to the underlying
    /// trader without requiring direct access to the kernel. Actors should be added
    /// after the node is built but before starting the node.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The trader is not in a valid state for adding components.
    /// - An actor with the same ID is already registered.
    /// - The node is currently running.
    pub fn add_actor<T>(&mut self, actor: T) -> anyhow::Result<()>
    where
        T: DataActor + DataActorNative + Component + Actor + 'static,
    {
        if self.state() != NodeState::Idle {
            anyhow::bail!(
                "Cannot add actor while node is running, add actors before running the node"
            );
        }

        self.kernel.trader.borrow_mut().add_actor(actor)
    }

    /// Adds an actor to the live node using a factory function.
    ///
    /// The factory function is called at registration time to create the actor,
    /// avoiding cloning issues with non-cloneable actor types.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The node is currently running.
    /// - The factory function fails to create the actor.
    /// - The underlying trader registration fails.

View on GitHub (pinned to 18893faf8b)