entry fragments have inconsistent parallelism settings in…

Error message

entry fragments have inconsistent parallelism settings in batch refresh job

What it means

When rendering actors for a batch refresh (time travel) job, all entry fragments must share one parallelism setting; deduplicating their parallelism yields more than one distinct value and the ensemble rendering fails. This is an internal consistency requirement for building the job's actor graph.

Solutions

Retry the refresh operation; a fresh plan may render consistent parallelism.
Check for concurrent ALTER (parallelism changes) on the table being refreshed and avoid them during refresh.
If reproducible, file a bug with the plan/fragment parallelism details — it indicates a frontend planning inconsistency.

Defensive patterns

Strategy: retry

Try / catch

match refresh_result {
    Err(e) if e.to_string().contains("inconsistent parallelism settings") => {
        // wait, avoid concurrent ALTER, retry the refresh once
    }
    other => other?,
}

Prevention

Avoid concurrent ALTER/parallelism changes while a refresh job is in flight.
Retry refreshes that fail with this message; a fresh plan usually renders consistently.
Escalate reproducible cases as frontend planning bugs.

When it happens

Trigger: A batch refresh job whose entry fragments were planned with differing parallelism (e.g. plan/parallelism adjustment between fragment creations) reaches render_actors_and_build_job_info.

Common situations: Plan-level bug where entry fragments get inconsistent parallelism; cluster parallelism changed between planning and rendering; post-upgrade metadata inconsistency in an in-flight refresh job.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/meta/src/barrier/checkpoint/independent_job/batch_refresh_job/mod.rs:258

            // Assert all component fragments share the same vnode count.
            for fid in ensemble.component_fragments() {
                let f = &fragments[&fid];
                assert_eq!(
                    vnode_count, f.vnode_count,
                    "fragments {} and {} in same ensemble have different vnode counts",
                    first_component, fid,
                );
            }

            let entry_fragment_parallelism = Itertools::exactly_one(
                ensemble
                    .entry_fragments()
                    .map(|fid| fragments[&fid].parallelism.clone())
                    .dedup(),
            )
            .map_err(|_| {
                anyhow!(
                    "entry fragments have inconsistent parallelism settings in batch refresh job"
                )
            })?;

            let actor_template = EnsembleActorTemplate::render_new(
                streaming_job_model,
                worker_nodes,
                entry_fragment_parallelism,
                database_resource_group.to_owned(),
                distribution_type,
                vnode_count,
            )?;

            for fid in ensemble.component_fragments() {
                let f = &fragments[&fid];
                let aligner =
                    ComponentFragmentAligner::new_persistent(&actor_template, actor_id_generator);
                let assignments = aligner.align_component_actor(f.distribution_type);

View on GitHub (pinned to 6469eb736d)