What causes "Stop the rollback due to shutdown signal received" in FuelLabs/fuel-core?

Restart the node and re-run the rollback — it is resumable; already-rolled-back heights are skipped.

Stop the rollback due to shutdown signal received

Error message

Stop the rollback due to shutdown signal received

What it means

rollback_to runs in a loop that checks a ShutdownListener each iteration so a shutting-down node stops promptly. If the listener reports cancellation before all databases reached the target height, the function returns this error instead of Ok — a partially completed rollback must not be reported as success. This is an expected, cooperative-shutdown error, not corruption; progress made so far is retained and the rollback resumes on the next attempt.

Source

Thrown at crates/fuel-core/src/combined_database.rs:591

            }

            #[cfg(feature = "rpc")]
            {
                let block_aggregation_storage_height = self
                    .block_aggregation_storage()
                    .latest_height_from_metadata()?;

                if let Some(block_aggregation_storage_height) =
                    block_aggregation_storage_height
                    && block_aggregation_storage_height > target_block_height
                {
                    self.block_aggregation_storage().rollback_last_block()?;
                }
            }
        }

        if shutdown_listener.is_cancelled() {
            return Err(anyhow::anyhow!(
                "Stop the rollback due to shutdown signal received"
            ));
        }

        Ok(())
    }

    /// Rollbacks the state of the relayer to a specific block height.
    pub fn rollback_relayer_to<S>(
        &self,
        target_da_height: DaBlockHeight,
        shutdown_listener: &mut S,
    ) -> anyhow::Result<()>
    where
        S: ShutdownListener,
    {
        while !shutdown_listener.is_cancelled() {
            let relayer_db_height = self.relayer().latest_height_from_metadata()?;

View on GitHub (pinned to b9d4d170da)

Solutions

Restart the node and re-run the rollback — it is resumable; already-rolled-back heights are skipped.
Avoid sending shutdown signals until rollback completes, or schedule rollbacks during maintenance windows.
Monitor the rollback progress and only stop once it reports success.

Defensive patterns

Strategy: retry

Validate before calling

// Nothing to validate ahead of time: the shutdown signal is external.
// Optional: check listener state before starting.
if shutdown_listener.is_cancelled() {
    anyhow::bail!("refusing to start rollback: shutdown already requested");
}
combined_db.rollback_to(target, &mut shutdown)?;

Try / catch

loop {
    match combined_db.rollback_to(target, &mut shutdown) {
        Ok(()) => break,
        Err(e) if e.to_string().contains("shutdown signal received") => {
            // partial rollback retained; resume after restart / when not cancelling
            if shutdown_listener.is_cancelled() { return Err(e); }
            continue;
        }
        Err(e) => return Err(e),
    }
}

Prevention

Run long rollbacks in maintenance windows with shutdown signals deferred.
Treat this error as 'incomplete, resumable' — never as corruption.
Log rollback progress so operators can see how much remains before stopping a node.

When it happens

Trigger: Node receives Ctrl-C / SIGTERM / service-manager stop while a rollback_to is in progress and not yet finished.

Common situations: Long rollbacks (large height gaps) interrupted by restarts, deployments, or orchestrator-driven shutdowns; CI environments killing nodes under test.

Related errors

AI-assisted analysis of FuelLabs/fuel-core@b9d4d170da (2026-08-16). Data as JSON: /api/errors/738c09463e26159e. Report an issue: GitHub.