risingwavelabs/risingwave · error · MetaError

cannot create batch refresh job while database barrier is pa

Error message

cannot create batch refresh job while database barrier is paused

What it means

A batch refresh (CreateStreamingJobType::BatchRefresh) job creation command was applied while the database's barrier state is paused. Batch refresh depends on a stable barrier snapshot epoch (prev_epoch), so the system rejects the operation until barriers resume.

Source

Thrown at src/meta/src/barrier/checkpoint/state.rs:683

                    let (table_ids, node_actors) = self.collect_base_info();
                    (
                        Some(mutation),
                        table_ids,
                        None,
                        node_actors,
                        PostCollectCommand::barrier(),
                    )
                }
            }
            Some(Command::CreateStreamingJob {
                mut info,
                job_type: CreateStreamingJobType::BatchRefresh(mut batch_refresh_info),
                cross_db_snapshot_backfill_info,
            }) => {
                notify_database_graph = false;
                {
                    if self.state.is_paused() {
                        bail!("cannot create batch refresh job while database barrier is paused");
                    }
                    let snapshot_epoch = barrier_info.prev_epoch();
                    let job_id = info.stream_job_fragments.stream_job_id();
                    let database_id = info.streaming_job.database_id();

                    // 1. Fill snapshot backfill epochs.
                    let snapshot_backfill_info = &mut batch_refresh_info.snapshot_backfill_info;
                    for snapshot_backfill_epoch in snapshot_backfill_info
                        .upstream_mv_table_id_to_backfill_epoch
                        .values_mut()
                    {
                        assert_eq!(
                            snapshot_backfill_epoch.replace(snapshot_epoch),
                            None,
                            "must not set previously"
                        );
                    }
                    for fragment in info.stream_job_fragments.inner.fragments.values_mut() {

View on GitHub (pinned to 6469eb736d)

Solutions

1. Resume the database (ALTER DATABASE ... RESUME) and retry the batch refresh
2. Check the pause state before submitting batch refresh
3. Wait for any pause-based operations (schema changes, backfills) to complete

Example fix

-- before
ALTER DATABASE db PAUSE;
CREATE ... BATCH REFRESH ...;
-- after
ALTER DATABASE db RESUME;
CREATE ... BATCH REFRESH ...;

if database_state.is_paused() {
    return Err("resume database before batch refresh");
}
submit_batch_refresh();

fn can_batch_refresh(state: &BarrierState) -> bool { !state.is_paused() }

match create_batch_refresh(...).await {
    Err(e) if e.contains("barrier is paused") => resume_and_retry(),
    other => other,
}

When it happens

Trigger: Applying a CREATE batch refresh job command via handle_new_barrier while the database is paused (e.g. after ALTER DATABASE ... PAUSE or an ongoing pause-based operation).

Common situations: User runs batch refresh while the database is paused for maintenance; another operation (e.g. schema change) left the database paused; script paused a database and forgot to resume before refreshing.

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

• entry fragments have inconsistent parallelism settings in ba
• since_timestamp epoch has not been resolved for snapshot bac
• replace sink must not use snapshot backfill
• old sink job {} not found in barrier state
• no table changelog found for upstream table {} when resolvin

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