What causes "Failed to get pool event-family checkpoints: {e}" in nautechsystems/nautilus_trader?

Apply migrations to create the event-family checkpoint table

nautechsystems/nautilus_trader · error · anyhow::Error

Failed to get pool event-family checkpoints: {e}

Error message

Failed to get pool event-family checkpoints: {e}

What it means

Wraps a sqlx error from the SELECT listing per-event-family checkpoint blocks for a pool. These checkpoints track independent event family progress (e.g. swaps vs mints). Failure aborts reconstruction of the pool's event sync state.

Source

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

            return Ok(PoolEventSyncState::default());
        };

        let family_blocks = sqlx::query_as::<_, (String, i64)>(
            "
            SELECT event_family, last_full_sync_block_number
            FROM pool_event_sync
            WHERE chain_id = $1
            AND dex_name = $2
            AND pool_identifier = $3
            ORDER BY event_family
            ",
        )
        .bind(chain_id as i32)
        .bind(dex.to_string())
        .bind(pool_identifier.as_ref())
        .fetch_all(&self.pool)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to get pool event-family checkpoints: {e}"))?
        .into_iter()
        .map(|(family, block)| (family, block as u64))
        .collect();

        Ok(PoolEventSyncState {
            version: version as u32,
            last_full_sync_block: last_full_sync_block.map(|block| block as u64),
            family_blocks,
        })
    }

    pub(crate) async fn update_pool_event_sync(
        &self,
        chain_id: u32,
        dex: &DexType,
        pool_identifier: &PoolIdentifier,
        event_families: &[&str],
        block_number: u64,

View on GitHub (pinned to 18893faf8b)

Solutions

Apply migrations to create the event-family checkpoint table
Check statement_timeout settings if the query is cancelled on large pools
Verify connectivity and retry
Inspect the wrapped sqlx error for the root cause

Defensive patterns

Strategy: retry

Validate before calling

sqlx::query("SELECT 1 FROM pool_event_family_checkpoints LIMIT 1").fetch_optional(&pool).await?;

Try / catch

let checkpoints = loop {
    match get_family_checkpoints(...).await {
        Ok(c) => break c,
        Err(e) if attempts < 3 => { attempts += 1; sleep(backoff).await; }
        Err(e) => return Err(e),
    }
};

Prevention

Create checkpoint tables via migrations
Set realistic statement_timeout for large pools
Retry idempotent reads with backoff

When it happens

Trigger: Calling the event-family checkpoint query inside `get_pool_event_sync_state` when the connection fails, the checkpoint table is missing, or the server errors (timeout/cancellation).

Common situations: Missing migrations on a new deployment; DB restart; long-running query cancelled by statement_timeout.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

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