What causes "Failed to send query add_instrument to database message handler: {e}" in nautechsystems/nautilus_trader?

Ensure the adapter's message-handler task is alive before adding instruments.

Failed to send query add_instrument to database message hand

Error message

Failed to send query add_instrument to database message handler: {e}

What it means

Thrown by `add_instrument` when the `DatabaseQuery::AddInstrument` message cannot be delivered to the database message-handler task over its mpsc channel, i.e. the receiver has been dropped. The instrument is not persisted.

Source

Thrown at crates/infrastructure/src/sql/cache.rs:923

    fn add(&self, key: String, value: Bytes) -> anyhow::Result<()> {
        let query = DatabaseQuery::Add(key, value.into());
        self.tx
            .send(query)
            .map_err(|e| anyhow::anyhow!("Failed to send query to database message handler: {e}"))
    }

    fn add_currency(&self, currency: &Currency) -> anyhow::Result<()> {
        let query = DatabaseQuery::AddCurrency(*currency);
        self.tx.send(query).map_err(|e| {
            anyhow::anyhow!("Failed to query add_currency to database message handler: {e}")
        })
    }

    fn add_instrument(&self, instrument: &InstrumentAny) -> anyhow::Result<()> {
        let query = DatabaseQuery::AddInstrument(instrument.clone());
        self.tx.send(query).map_err(|e| {
            anyhow::anyhow!("Failed to send query add_instrument to database message handler: {e}")
        })
    }

    fn add_instrument_close(&self, close: &InstrumentClose) -> anyhow::Result<()> {
        self.tx
            .send(DatabaseQuery::AddInstrumentClose(*close))
            .map_err(|e| {
                anyhow::anyhow!(
                    "Failed to send query add_instrument_close to database message handler: {e}"
                )
            })
    }

    fn add_synthetic(&self, _synthetic: &SyntheticInstrument) -> anyhow::Result<()> {
        todo!()
    }

    fn add_account(&self, account: &AccountAny) -> anyhow::Result<()> {

View on GitHub (pinned to 18893faf8b)

Solutions

Ensure the adapter's message-handler task is alive before adding instruments.
Check handler logs for panics.
Reconnect/restart the cache database client and retry.
In Python, avoid calling `py_add_instrument` after adapter disconnect.

Defensive patterns

Strategy: try-catch

Validate before calling

if not cache_db_adapter.is_running:
    raise RuntimeError("Cannot add_instrument: adapter not running")

Try / catch

try:
    cache.add_instrument(instrument)
except RuntimeError as e:
    logger.error("Instrument persistence failed (writer stopped): %s", e)

Prevention

Load instruments before starting data/trading flows
Keep the writer task alive until all instruments are added
Log and handle SendError-like failures explicitly
Reconnect the adapter on failure instead of dropping writes silently

When it happens

Trigger: Calling `add_instrument` (via `py_add_instrument` or `seed_order_event_dependencies`) when the writer task is gone — adapter stopped, handler panicked, or process is shutting down.

Common situations: Adding instruments to a cache database whose background writer already terminated; shutdown-ordering bugs in live trading setups.

Related errors

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