nautechsystems/nautilus_trader · error · anyhow::Error

Failed to insert into pool_snapshot table: {e}

Error message

Failed to insert into pool_snapshot table: {e}

What it means

Raised when a single-row INSERT of a pool snapshot into the `pool_snapshot` table (including analytics fields such as total fee-collects, flashes, and liquidity utilization rate) fails. The sqlx error is wrapped with this message. The snapshot is not saved, which can break checkpoint/replay start points that depend on snapshots.

Source

Thrown at crates/adapters/blockchain/src/cache/database.rs:2116

        .bind(snapshot.state.fee_protocol as i16)
        .bind(snapshot.state.fee_protocol0_basis_points.map(|v| v as i32))
        .bind(snapshot.state.fee_protocol1_basis_points.map(|v| v as i32))
        .bind(snapshot.state.fee_growth_global_0.to_string())
        .bind(snapshot.state.fee_growth_global_1.to_string())
        .bind(snapshot.analytics.total_amount0_deposited.to_string())
        .bind(snapshot.analytics.total_amount1_deposited.to_string())
        .bind(snapshot.analytics.total_amount0_collected.to_string())
        .bind(snapshot.analytics.total_amount1_collected.to_string())
        .bind(snapshot.analytics.total_swaps as i32)
        .bind(snapshot.analytics.total_mints as i32)
        .bind(snapshot.analytics.total_burns as i32)
        .bind(snapshot.analytics.total_fee_collects as i32)
        .bind(snapshot.analytics.total_flashes as i32)
        .bind(snapshot.analytics.liquidity_utilization_rate)
        .execute(&self.pool)
        .await
        .map(|_| ())
        .map_err(|e| anyhow::anyhow!("Failed to insert into pool_snapshot table: {e}"))
    }

    /// Inserts multiple pool positions in a single database operation using UNNEST for optimal performance.
    ///
    /// # Errors
    ///
    /// Returns an error if the database operation fails.
    pub async fn add_pool_positions_batch(
        &self,
        chain_id: u32,
        snapshot_block: u64,
        snapshot_transaction_index: u32,
        snapshot_log_index: u32,
        positions: &[(PoolIdentifier, PoolPosition)],
    ) -> anyhow::Result<()> {
        if positions.is_empty() {
            return Ok(());
        }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Read the `{e}` suffix for the exact sqlx/PostgreSQL error
2. Ensure the referenced pool row exists before inserting its snapshot (FK order)
3. Run pending migrations to match the pool_snapshot schema
4. Validate analytics fields (non-negative counts, utilization rate within column bounds) before inserting
5. Check connection health and retry after transient failures

Example fix

// before
.map_err(|e| anyhow::anyhow!("Failed to insert into pool_snapshot table: {e}"))
// after: ensure parent row exists and surface pool context
// ensure pool row for snapshot.pool_identifier is inserted first
.map_err(|e| anyhow::anyhow!("Failed to insert into pool_snapshot table (pool={}, block={}): {e}", snapshot.pool_identifier, snapshot.block))

fn validate_snapshot(snapshot: &PoolSnapshot) -> anyhow::Result<()> {
    anyhow::ensure!(!snapshot.pool_identifier.is_empty(), "missing pool_identifier");
    anyhow::ensure!(snapshot.analytics.liquidity_utilization_rate >= 0.0, "negative utilization");
    Ok(())
}

fn is_persistable(snapshot: &PoolSnapshot) -> bool {
    !snapshot.pool_identifier.is_empty() && snapshot.block > 0
}

match add_pool_snapshot(&snapshot).await {
    Ok(()) => {},
    Err(e) if e.to_string().contains("foreign key") => {
        ensure_pool_row(&snapshot.pool_identifier).await?;
        add_pool_snapshot(&snapshot).await?;
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling the add-pool-snapshot method when Postgres rejects the row: NOT NULL violation on an analytics field, numeric precision overflow for utilization rate, FK violation if the referenced pool row does not exist yet, or connection loss.

Common situations: Inserting a snapshot for a pool not yet present in the pools table (FK failure); utilization-rate floats exceeding column precision; schema drift after migrations; database restarts mid-run.

Related errors

• Failed to seed chain table: {e}
• Failed to call create_block_partition for chain {}: {e}
• Failed to call create_token_partition for chain {}: {e}
• Failed to get block info for chain {}: {}
• Failed to insert into block table: {e}

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