specified parallelism {n} should not exceed max parallelism

Error message

specified parallelism {n} should not exceed max parallelism {max_parallelism}

What it means

`reschedule_inplace` applies a `ReschedulePolicy::Parallelism` (or `Both`) to a streaming job. When the policy uses `StreamingParallelism::Fixed(n)` and `n` exceeds the job's `max_parallelism` limit, the meta service rejects the reschedule with this error instead of silently over-parallelizing the job.

Source

Thrown at src/meta/src/stream/scale.rs:246

        let inner = self.metadata_manager.catalog_controller.inner.write().await;
        let txn = inner.db.begin().await?;

        for (table_id, target) in &policy {
            let streaming_job = StreamingJob::find_by_id(*table_id)
                .one(&txn)
                .await?
                .ok_or_else(|| MetaError::catalog_id_not_found("table", table_id))?;

            let max_parallelism = streaming_job.max_parallelism;

            let mut streaming_job = streaming_job.into_active_model();

            match &target {
                ReschedulePolicy::Parallelism(p) | ReschedulePolicy::Both(p, _) => {
                    if let StreamingParallelism::Fixed(n) = p.parallelism
                        && n > max_parallelism as usize
                    {
                        bail!(format!(
                            "specified parallelism {n} should not exceed max parallelism {max_parallelism}"
                        ));
                    }

                    streaming_job.parallelism = Set(p.parallelism.clone());
                    if matches!(p.parallelism, StreamingParallelism::Fixed(_)) {
                        streaming_job.adaptive_parallelism_strategy = Set(None);
                    } else {
                        streaming_job.adaptive_parallelism_strategy =
                            Set(p.adaptive_parallelism_strategy.clone());
                    }
                }
                _ => {}
            }

            match &target {
                ReschedulePolicy::ResourceGroup(r) | ReschedulePolicy::Both(_, r) => {
                    streaming_job.specific_resource_group = Set(r.resource_group.clone());

View on GitHub (pinned to 6469eb736d)

Solutions

Query the job's max_parallelism (e.g. via SHOW / rw_catalog) and set a fixed parallelism <= that value.
Use `Adaptive` parallelism instead of `Fixed` so the framework picks a legal value.
If a higher fixed parallelism is genuinely needed, recreate the job with a larger max_parallelism, then reschedule.

Example fix

// before
ALTER TABLE t SET PARALLELISM = 16;
// after (with max_parallelism = 8)
ALTER TABLE t SET PARALLELISM = 8;

Defensive patterns

Strategy: validation

Validate before calling

// look up max_parallelism (e.g. from rw_catalog.rw_streaming_jobs) before issuing the reschedule
let max = get_job_max_parallelism(job_id).await?;
if let StreamingParallelism::Fixed(n) = &policy.parallelism {
    if *n > max { return Err(format!("requested {n} exceeds max {max}")); }
}

Try / catch

match reschedule(job_id, policy).await {
    Err(e) if e.to_string().contains("should not exceed max parallelism") => {
        // fall back to a legal value
        reschedule(job_id, policy.with_fixed(max_parallelism)).await?
    }
    r => r?,
}

Prevention

Query the job's max_parallelism from the catalog before setting a fixed parallelism.
Prefer Adaptive parallelism when the optimal value is unknown.
Document max_parallelism alongside job settings so operators don't guess.

When it happens

Trigger: Submitting an ALTER/RESCHEDULE request with `parallelism = fixed(n)` where `n > max_parallelism` of the streaming job — e.g. `ALTER TABLE t SET PARALLELISM = 16` on a job created with max parallelism 8, or a `Both` policy carrying an over-limit fixed parallelism.

Common situations: Operator sizing a job's parallelism above the cluster/job limit defined at creation; copy-pasting parallelism settings between jobs with different max_parallelism; increasing parallelism after the max was lowered.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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