databendlabs/databend · error

AggregateMeta does not support exchanging between multiple…

Error message

AggregateMeta does not support exchanging between multiple nodes

What it means

`AggregateMeta` implements `serde::Serialize` solely to panic. Aggregate partial results are exchanged within a node via shared state, not serialized over the wire, so any attempt to serialize this metadata means an aggregate pipeline was (incorrectly) set up for cross-node data exchange.

Solutions

1. Check the query plan (EXPLAIN) to see why aggregation fragments are exchanged across nodes instead of executed locally
2. Avoid the affected plan shape (e.g. adjust aggregation/exchange planning or query patterns) until fixed
3. Serialize AggregateMeta properly if cross-node exchange of partial aggregate state is required, or return an explicit error
4. Report with cluster topology and plan; this is a plan-exchange bug, not a user data problem

Example fix

// before
fn serialize<S>(&self, _: S) -> Result<S::Ok, S::Error> {
    unreachable!("AggregateMeta does not support exchanging between multiple nodes")
}
// after
fn serialize<S>(&self, _: S) -> Result<S::Ok, S::Error> {
    Err(serde::ser::Error::custom("AggregateMeta does not support exchanging between multiple nodes"))
}

fn is_exchangable<M: FragmentKind>(m: &M) -> bool { /* AggregateMeta must never be scheduled for cross-node exchange */ !m.requires_local_execution() }

When it happens

Trigger: The distributed execution framework attempts to `serde::serialize` an `AggregateMeta` fragment, which only happens if an aggregation pipeline fragment is exchanged between cluster nodes.

Common situations: Distributed aggregation plan bugs where fragments containing AggregateMeta are routed to remote nodes instead of being kept local; cluster deployments exercising exchange paths that local runs never hit.

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

• _ => unreachable!()
• not implemented: AggregateMeta does not support exchanging…
• DataExchange::Merge(_) => unreachable!()
• DataExchange::Broadcast(_) => unreachable!()
• DataExchange::GlobalShuffleExchange(_) => unreachable!()

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/f37835e5481b2482. Report an issue: GitHub.

Appendix: source

Thrown at src/query/service/src/pipelines/processors/transforms/aggregator/aggregate_meta.rs:296

    }

    pub fn create_spilled(payloads: Vec<SpilledPayload>) -> BlockMetaInfoPtr {
        Box::new(AggregateMeta::Spilled(payloads))
    }

    pub fn create_partitioned(bucket: Option<isize>, data: PartitionedData) -> BlockMetaInfoPtr {
        Box::new(AggregateMeta::Partitioned { bucket, data })
    }

    pub fn into_datablock(self) -> DataBlock {
        DataBlock::empty_with_meta(Box::new(self))
    }
}

impl serde::Serialize for AggregateMeta {
    fn serialize<S>(&self, _: S) -> std::result::Result<S::Ok, S::Error>
    where S: serde::Serializer {
        unreachable!("AggregateMeta does not support exchanging between multiple nodes")
    }
}

impl<'de> serde::Deserialize<'de> for AggregateMeta {
    fn deserialize<D>(_: D) -> std::result::Result<Self, D::Error>
    where D: serde::Deserializer<'de> {
        unreachable!("AggregateMeta does not support exchanging between multiple nodes")
    }
}

impl Debug for AggregateMeta {
    fn fmt(&self, f: &mut Formatter) -> std::fmt::Result {
        match self {
            AggregateMeta::Partitioned { .. } => {
                f.debug_struct("AggregateMeta::Partitioned").finish()
            }
            AggregateMeta::Serialized { .. } => {
                f.debug_struct("AggregateMeta::Serialized").finish()

View on GitHub (pinned to 288d84d76e)