dbt-labs/dbt-core · error

Left key " " does not have a matching right key.

Error message

Left key "{}" does not have a matching right key.

What it means

Fires during the hash-join row matching in Table.join: a column listed in left_key has no counterpart in right_key, so the join cannot pair rows. The message interpolates the offending left key name; the fault is mismatched key column lists in the Jinja join() call.

Solutions

1. Give right_key the same number and order of column names as left_key
2. Check spelling and case of the key column names on both tables
3. Verify both key columns exist in their respective tables before joining

When it happens

Trigger: Thrown at crates/dbt-agate/src/join.rs:234 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/b81562374023a7b6. Report an issue: GitHub.

Appendix: source

Thrown at crates/dbt-agate/src/join.rs:234

        //             ...
        //             rows.append(Row(new_row, column_names))
        // ```
        //
        // Instead of materializing the rows, the joined table is described as pairs of
        // row indices into the left and the right table. `None` on either side means the
        // row has no counterpart there and the columns of that side are NULL.
        let mut joined_rows: Vec<(Option<usize>, Option<usize>)> = Vec::new();
        for left_row_idx in 0..self.num_rows() {
            match right_hash.get(&left_tuple_hasher.hash_row(left_row_idx)) {
                Some(right_row_indices) => {
                    // one joined row per matching right row
                    for &right_row_idx in right_row_indices {
                        joined_rows.push((Some(left_row_idx), Some(right_row_idx)));
                    }
                }
                None => {
                    if require_match {
                        return Err(Error::new(
                            ErrorKind::InvalidOperation,
                            format!(
                                "Left key \"{}\" does not have a matching right key.",
                                left_key.key_of_row(self, left_row_idx)
                            ),
                        ));
                    }
                    if !join_type.is_inner() {
                        joined_rows.push((Some(left_row_idx), None));
                    }
                }
            }
        }

        // ```python
        //     # Full outer join
        //     if full_outer:
        //         left_set = set(left_data)

View on GitHub (pinned to 0267ce9170)