nautechsystems/nautilus_trader · error

Failed to load instrument with id

Error message

Failed to load instrument with id {instrument_id},error is: {e}

What it means

`DatabaseQueries::load_instrument` runs `SELECT * FROM instrument WHERE id = $1` and returns Ok(None) for a missing row — not-found is not an error. This anyhow error is raised only on execution failure (connectivity, missing table) or row-decoding failure, where a stored instrument row can't be converted into `InstrumentAny`, typically due to schema drift or an enum/kind value written by a different version.

Solutions

  1. Run migrations matching this code version so the table and enum types decode correctly.
  2. Identify the undecodable row from the inner sqlx decode error; upgrade the binary or re-write the row with the current version.
  3. Confirm DATABASE_URL targets the correct cache database.
  4. Treat Ok(None) as 'instrument not cached' and handle it separately from this error.

Example fix

// before
let instrument = DatabaseQueries::load_instrument(&pool, &instrument_id).await?;
// after
let instrument = match DatabaseQueries::load_instrument(&pool, &instrument_id).await? {
    Some(instrument) => Some(instrument),
    None => {
        tracing::warn!("instrument {instrument_id} not in cache");
        None
    }
};
Defensive patterns

Strategy: try-catch

Validate before calling

let exists: bool = sqlx::query_scalar(
    "SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = 'instrument')",
).fetch_one(pool).await?;
if !exists {
    return Err(anyhow::anyhow!("'instrument' table missing — run migrations"));
}

Try / catch

match DatabaseQueries::load_instrument(&pool, &instrument_id).await {
    Ok(Some(instrument)) => Some(instrument),
    Ok(None) => {
        tracing::warn!("instrument {instrument_id} not in cache");
        None
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: Calling `DatabaseQueries::load_instrument(pool, instrument_id)` when the connection fails, the `instrument` table doesn't exist, or the row fails to decode (e.g. a newer instrument kind or asset_class value the current decoder rejects, or a malformed numeric column).

Common situations: Loading instruments at strategy startup from a database written by a different Nautilus version; fresh DB without migrations; rows containing new enum variants; transient network failure during the lookup.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors


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

Appendix: source

Thrown at crates/infrastructure/src/sql/queries.rs:225

            .map_err(|e| anyhow::anyhow!("Failed to insert item {} into instrument table: {:?}", instrument.id(), e))
    }

    /// Loads a single `InstrumentAny` entry by `instrument_id` via the provided `pool`.
    ///
    /// # Errors
    ///
    /// Returns an error if the SELECT operation fails.
    pub async fn load_instrument(
        pool: &PgPool,
        instrument_id: &InstrumentId,
    ) -> anyhow::Result<Option<InstrumentAny>> {
        sqlx::query_as::<_, InstrumentAnyRow>("SELECT * FROM instrument WHERE id = $1")
            .bind(instrument_id.to_string())
            .fetch_optional(pool)
            .await
            .map(|instrument| instrument.map(|row| row.0))
            .map_err(|e| {
                anyhow::anyhow!("Failed to load instrument with id {instrument_id},error is: {e}")
            })
    }

    /// Loads all `InstrumentAny` entries via the provided `pool`.
    ///
    /// # Errors
    ///
    /// Returns an error if the SELECT operation fails.
    pub async fn load_instruments(pool: &PgPool) -> anyhow::Result<Vec<InstrumentAny>> {
        sqlx::query_as::<_, InstrumentAnyRow>("SELECT * FROM instrument")
            .fetch_all(pool)
            .await
            .map(|rows| rows.into_iter().map(|row| row.0).collect())
            .map_err(|e| anyhow::anyhow!("Failed to load instruments: {e}"))
    }

    /// Inserts or replaces an `InstrumentClose`.
    ///

View on GitHub (pinned to 18893faf8b)