nautechsystems/nautilus_trader · critical

Failed to connect to the Postgres cache database: {e}

Error message

Failed to connect to the Postgres cache database: {e}

What it means

The client lazily connects to the configured Postgres cache database via BlockchainCacheDatabase::connect during setup. If the connection cannot be established, the error is wrapped as "Failed to connect to the Postgres cache database". This is a hard failure because durable payload storage is mandatory for Postgres-backed execution.

Source

Thrown at crates/adapters/blockchain/src/execution/client.rs:5883

        if self.cache.database.is_some() || self.config.postgres_cache_database_config.is_some() {
            let keys = payload_keys.as_deref().ok_or_else(|| {
                anyhow::anyhow!(
                    "Postgres execution requires an active payload key and deployment identity"
                )
            })?;

            if self.cache.database.is_none() {
                let pg_options = self
                    .config
                    .postgres_cache_database_config
                    .as_ref()
                    .expect("Postgres configuration checked above");
                let database = crate::cache::database::BlockchainCacheDatabase::connect(
                    pg_options.clone().into(),
                )
                .await
                .map_err(|e| {
                    anyhow::anyhow!("Failed to connect to the Postgres cache database: {e}")
                })?;
                self.cache.database = Some(database);
            }
            self.cache
                .database
                .as_ref()
                .expect("database was attached")
                .require_execution_payload_storage_ready(keys)
                .await?;
            self.cache.initialize_chain().await;
            self.cache.ensure_execution_transaction_schema().await?;
            let check = self
                .cache
                .database
                .as_ref()
                .expect("database was attached")
                .check_execution_payload_storage(
                    Some(keys),

View on GitHub (pinned to 18893faf8b)

Solutions

1. Check the inner error {e} to distinguish DNS/refused/auth/TLS failures and fix accordingly
2. Verify postgres_cache_database_config host, port, database, user, and password against the actual Postgres instance
3. Test connectivity from the same host/network (psql or pg_isready) to rule out firewalls and DNS issues
4. Confirm the Postgres server is running and accepting connections (max_connections, logs), then retry startup

Example fix

// before
postgres_cache_database_config = Some(PgConfig { host: "db.internal", port: 5432, ... })
// after (verified reachable & credentials valid)
postgres_cache_database_config = Some(PgConfig { host: "db.internal", port: 5433, user: "nautilus", password: <from secret>, ssl_mode: require })

// preflight connectivity check before startup
let res = tokio::net::TcpStream::connect((host, port)).await;
assert!(res.is_ok(), "Postgres host {host}:{port} unreachable");

// wrap connect with bounded retries
for attempt in 1..=3 {
    match try_start_client(config.clone()).await {
        Err(e) if e.to_string().contains("Failed to connect to the Postgres cache database") => {
            log::warn!("pg connect failed (attempt {attempt}): {e}");
            tokio::time::sleep(Duration::from_secs(2u64.pow(attempt))).await;
        }
        other => { other?; break; }
    }
}

When it happens

Trigger: Startup with postgres_cache_database_config set where the TCP/TLS connection to Postgres fails, credentials are rejected, the database/host is wrong, or the server is unreachable/overloaded.

Common situations: Wrong host/port in the cache database config; firewall or security group blocking the port; expired or rotated DB credentials; Postgres down or at max_connections; TLS certificate mismatch; DNS resolution failure in containerized deployments.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Could not calculate schema dir from current directory path o
• Error executing statement {sql_statement} with error: {e:?}
• Error dropping role {database}: {e:?}
• Failed to load order events: {e}
• Failed to start COPY operation: {e}

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