risingwavelabs/risingwave · error · Error

failed to match fragment

Error message

failed to match fragment {id}: {message}

What it means

A `state_match::Error::Fragment` variant raised when the matcher fails to match a whole fragment (identified by `id`) between the old and new stream graph. It carries an optional source chain (`Error`) pointing at the operator-level cause plus a message describing the fragment-level mismatch.

Solutions

1. Inspect the nested source error to find the operator-level mismatch and address that.
2. Limit the ALTER to supported column changes that preserve fragment structure; otherwise recreate the streaming job.
3. Keep frontend and meta on compatible versions so fragment ids/structures remain matchable.

null

if let state_match::Error::Fragment { id, message, .. } = &err {
    eprintln!("fragment {} mismatched: {}", id, message);
}

match state_match::match_graph(&old, &new) {
    Err(state_match::Error::Fragment { id, source, .. }) => {
        tracing::warn!("fragment {} unmatched (source: {:?}); consider recreating the job", id, source);
    }
    Err(e) => return Err(e.into()),
    Ok(tables) => apply(tables),
}

When it happens

Trigger: During schema-change state table matching, when a fragment in the new graph cannot be paired with one in the old graph — missing corresponding fragment, changed fragment identity, or a nested operator match error propagated up.

Common situations: ALTERs that add/remove/reorder operators so fragment structures differ; jobs where dispatchers or upstream ids changed between versions.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• failed to match graph
• failed to match operator
• sink with auto schema change should have only 1 fragment…
• unsupported job type for replacement
• id not found

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

Appendix: source

Thrown at src/meta/src/stream/stream_graph/state_match.rs:59

        let body = node.node_body.as_ref().unwrap();

        Self(format!("{}({}, {})", body, id, identity).into_boxed_str())
    }
}

impl std::fmt::Display for StreamNodeDesc {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// Error type for failed state table matching.
#[derive(thiserror::Error, thiserror_ext::Macro, thiserror_ext::ReportDebug)]
pub(crate) enum Error {
    #[error("failed to match graph: {message}")]
    Graph { message: String },

    #[error("failed to match fragment {id}: {message}")]
    Fragment {
        source: Option<Box<Error>>,
        id: Id,
        message: String,
    },

    #[error("failed to match operator {from} to {to}: {message}")]
    Operator {
        from: StreamNodeDesc,
        to: StreamNodeDesc,
        message: String,
    },
}

type Result<T, E = Error> = std::result::Result<T, E>;

/// Fragment id.
type Id = FragmentId;

View on GitHub (pinned to 6469eb736d)