risingwavelabs/risingwave · warning

The cluster is bootstrapping

Error message

The cluster is bootstrapping

What it means

check_status_running validates that the barrier manager is in Running state before serving commands. When the status is Starting or Recovering with RecoveryReason::Bootstrap, it reports 'The cluster is bootstrapping'. Any DDL/DML requiring barrier progress is rejected until bootstrap completes.

Source

Thrown at src/meta/src/barrier/manager.rs:169

            ))
            .context("failed to send update database barrier request")?;
        rx.await.context("failed to wait update database barrier")?;
        Ok(())
    }

    pub async fn get_hummock_version_id(&self) -> HummockVersionId {
        self.hummock_manager.get_version_id().await
    }
}

impl GlobalBarrierManager {
    /// Check the status of barrier manager, return error if it is not `Running`.
    pub fn check_status_running(&self) -> MetaResult<()> {
        let status = self.status.load();
        match &**status {
            BarrierManagerStatus::Starting
            | BarrierManagerStatus::Recovering(RecoveryReason::Bootstrap) => {
                bail!("The cluster is bootstrapping")
            }
            BarrierManagerStatus::Recovering(RecoveryReason::Failover(e)) => {
                Err(anyhow::anyhow!(e.clone()).context("The cluster is recovering"))?
            }
            BarrierManagerStatus::Recovering(RecoveryReason::Adhoc) => {
                bail!("The cluster is recovering-adhoc")
            }
            BarrierManagerStatus::Running => Ok(()),
        }
    }

    pub fn get_recovery_status(&self) -> PbRecoveryStatus {
        (&**self.status.load()).into()
    }
}

impl GlobalBarrierManager {
    #[expect(clippy::too_many_arguments)]

View on GitHub (pinned to 6469eb736d)

Solutions

1. Wait for cluster readiness (health/ready endpoint or successful `SELECT 1`) before issuing statements
2. Add retry-with-backoff around DDL/DML during startup windows
3. Check meta node logs to confirm bootstrap finished; if stuck, investigate the initial barrier schedule
4. Increase startup wait in test harnesses

Example fix

// before
run_query(sql);
// after
wait_for_rw_ready(); // e.g. poll psql 'SELECT 1' until success
run_query(sql);

// poll readiness before DDL/DML
while cluster_status() != BarrierManagerStatus::Running { sleep(Duration::from_millis(500)).await; }

match err.to_string().as_str() {
    "The cluster is bootstrapping" => retry_with_backoff(|| run_statement()),
    _ => return Err(err),
}

When it happens

Trigger: Issuing SQL/API requests during initial cluster startup, before the barrier manager has finished bootstrapping and moved to Running.

Common situations: Clients connecting immediately after `risedev d` or cluster start; CI scripts that don't wait for readiness; retry loops hammering a fresh cluster.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• since_timestamp epoch has not been resolved for snapshot bac
• since_timestamp requires at least one upstream table
• The cluster is recovering
• The cluster is recovering-adhoc
• total_memory_bytes {} is larger than the total memory availa

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/fcec469b691a4f6c. Report an issue: GitHub.