Table or source '{}' specified in backfill_order is not used

Error message

Table or source '{}' specified in backfill_order is not used in the query

What it means

When building a fixed backfill order, plan_fixed_strategy resolves the `start` relation of each backfill_order pair and validates that its relation id appears among the relation ids actually scanned by the query. If the named table/source is not part of the query plan, creation fails with this error.

Source

Thrown at src/frontend/src/optimizer/backfill_order_strategy.rs:321

    }

    pub(super) fn plan_fixed_strategy(
        session: &SessionImpl,
        orders: Vec<(ObjectName, ObjectName)>,
        plan: StreamPlanRef,
    ) -> Result<HashMap<RelationId, HashSet<RelationId>>> {
        // Collect all scanned relation IDs from the plan.
        let scanned_relation_ids = collect_scanned_relation_ids(session, plan);

        let mut order: HashMap<RelationId, HashSet<RelationId>> = HashMap::new();
        for (start_name, end_name) in orders {
            let start_relation_id = bind_backfill_relation_id_by_name(session, start_name.clone())?;
            let end_relation_id = bind_backfill_relation_id_by_name(session, end_name.clone())?;

            // Validate that both relations are present in the query plan
            let Some(start_scanned_relation_ids) = scanned_relation_ids.get(&start_relation_id)
            else {
                bail!(
                    "Table or source '{}' specified in backfill_order is not used in the query",
                    start_name
                );
            };
            let Some(end_scanned_relation_ids) = scanned_relation_ids.get(&end_relation_id) else {
                bail!(
                    "Table or source '{}' specified in backfill_order is not used in the query",
                    end_name
                );
            };

            for start_scanned_relation_id in start_scanned_relation_ids {
                order
                    .entry(*start_scanned_relation_id)
                    .or_default()
                    .extend(end_scanned_relation_ids.iter().copied());
            }
        }

View on GitHub (pinned to 6469eb736d)

Solutions

Check every name in backfill_order against the tables/sources actually used in the MV query.
Remove or fix the unused relation in the backfill_order clause.
If the table was intentionally removed from the query, update backfill_order to reference only present relations.
Re-check table names for typos and exact case.

Example fix

// before
CREATE MATERIALIZED VIEW mv AS SELECT ... FROM t1 JOIN t2
WITH (backfill_order = 't3 -> t1');
// after
CREATE MATERIALIZED VIEW mv AS SELECT ... FROM t1 JOIN t2
WITH (backfill_order = 't1 -> t2');

Defensive patterns

Strategy: validation

Validate before calling

-- confirm the start relation appears in the MV query before creating
SELECT * FROM rw_catalog.rw_tables WHERE name = 't1';
-- and ensure t1 is referenced in the CREATE MATERIALIZED VIEW statement

Try / catch

match create_mv_result {
    Err(e) if e.to_string().contains("specified in backfill_order is not used") => {
        eprintln!("Fix backfill_order: reference only relations in the query");
    }
    other => other?,
}

Prevention

Derive backfill_order from the tables actually listed in the query's FROM/JOIN clauses.
Keep query text and backfill_order in the same migration/PR so they change together.
Test MV creation on a dev cluster before production DDL.

When it happens

Trigger: Creating a materialized view with a backfill_order option whose start (or end) table/source name does not correspond to any relation referenced by the MV query.

Common situations: Copy-pasted backfill_order clauses from another MV, renamed or dropped tables, listing intermediate tables that the planner optimized away, or referencing a source that the query no longer reads.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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