What causes "Join key types are not aligned: LHS: {outer_type:?}, RHS: {inner_type:?}" in risingwavelabs/risingwave?

Verify the inner table schema matches what the join plan was built against; refresh the plan

Join key types are not aligned: LHS: {outer_type:?}, RHS: {i

Error message

Join key types are not aligned: LHS: {outer_type:?}, RHS: {inner_type:?}

What it means

When building scan ranges for the inner side of a distributed lookup join, each outer join-key Datum's type must exactly match the corresponding inner-side key column type; otherwise the datum would be pushed into an eq_cond with the wrong type. The code bails with this message naming the mismatched LHS (outer) and RHS (inner) types.

Source

Thrown at src/batch/executors/src/executor/join/distributed_lookup_join.rs:340

        let mut scan_range = ScanRange::full_table_scan();

        for ((datum, outer_type), inner_type) in key_datums
            .into_iter()
            .zip_eq_fast(
                self.outer_side_key_types
                    .iter()
                    .take(self.lookup_prefix_len),
            )
            .zip_eq_fast(
                self.inner_side_key_types
                    .iter()
                    .take(self.lookup_prefix_len),
            )
        {
            let datum = if inner_type == outer_type {
                datum
            } else {
                bail!("Join key types are not aligned: LHS: {outer_type:?}, RHS: {inner_type:?}");
            };

            scan_range.eq_conds.push(datum);
        }

        let pk_prefix = OwnedRow::new(scan_range.eq_conds);

        if self.lookup_prefix_len == self.table.pk_indices().len() {
            let row = self.table.get_row(&pk_prefix, self.epoch.into()).await?;

            if let Some(row) = row {
                self.row_list.push(row);
            }
        } else {
            let iter = self
                .table
                .batch_iter_with_pk_bounds(
                    self.epoch.into(),

View on GitHub (pinned to 6469eb736d)

Solutions

Verify the inner table schema matches what the join plan was built against; refresh the plan
Recreate/refresh the materialized view or table so key column types align with the outer side
Ensure the frontend applies implicit casts so outer key datums match inner key types before lookup

Defensive patterns

Strategy: validation

Validate before calling

fn keys_aligned(outer_types: &[DataType], inner_types: &[DataType]) -> bool {
    outer_types.len() == inner_types.len()
        && outer_types.iter().zip(inner_types).all(|(o, i)| o == i)
}

Try / catch

match executor_result {
    Err(e) if e.to_string().contains("Join key types are not aligned") => {
        // re-plan with current schema / re-create lookup table before retrying
    }
    other => other?,
}

Prevention

Apply implicit casts on join keys in the planner so both sides share one DataType
After altering a lookup table's column types, always re-plan queries touching it
Add a planner test asserting lookup join key types match across sides

When it happens

Trigger: add_scan_range is invoked with outer key datums whose DataType differs from the inner table's key column types — e.g. after a schema change of the materialized/inner table, or a planner bug producing mismatched key types between the join's two sides.

Common situations: Altering the inner table's column type after the join plan was created; stale plans referencing an old table schema; type coercion not applied in the lookup-prefix key extraction.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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