Table.group_by_key: error creating grouper for key

Error message

Table.group_by_key: error creating grouper for key '{key}': {e}

What it means

group_by_key builds an internal grouper over the key column to produce row-index groups. If the underlying grouper construction fails (e.g. the key column does not exist or its type is unsupported for grouping), the error is wrapped in this message naming the key.

Solutions

Verify the key name matches an existing column in the table (check column_names / schema).
Group on a primitive-typed column; cast complex columns to a supported type first.
Inspect the inner error message (embedded after ': {e}') for the root cause, e.g. unknown column vs unsupported dtype.

Example fix

// before
table.group_by_key("catergory", None, None)? // typo
// after
table.group_by_key("category", None, None)?

Defensive patterns

Strategy: validation

Validate before calling

if !table.column_names().contains(&key.to_string()) {
    return Err(format!("key column '{key}' not found in table"));
}

Try / catch

match table.group_by_key(key, key_type, None) {
    Ok(groups) => groups,
    Err(e) if e.to_string().contains("error creating grouper") => {
        eprintln!("{e}");
        // verify column name/type, cast, and retry
        return Err(e);
    }
}

Prevention

Check the key name against the table schema before grouping.
Group on primitive-typed columns (Utf8, Int64, etc.); cast nested types first.
Log the inner wrapped error to distinguish missing column from unsupported dtype.

When it happens

Trigger: Calling table.group_by_key with a key name that is not an existing column, or with a key column whose Arrow data type the grouper cannot handle (e.g. nested/list types).

Common situations: Typo in the key column name; schema changed upstream so the expected key column is missing or renamed; grouping on a struct/list column that the grouper does not support.

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 dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/213488624af21e95. Report an issue: GitHub.

Appendix: source

Thrown at crates/dbt-agate/src/table.rs:858

    }

    fn group_by_key(
        &self,
        key: &str,
        key_name: &str,
        key_type: Option<crate::DataType>,
    ) -> Result<TableSet, Error> {
        let column = self
            .column_names_iter()
            .position(|n| n == key)
            .map(|idx| Column::new(idx, Arc::clone(&self.repr)));

        let key_type = key_type.or_else(|| column.as_ref().and_then(|c| c.data_type().cloned()));

        // TODO: cast the values in `column` according to `key_type`, create a new
        // table with the casted column, and use that table to create the grouper
        let grouper = self.grouper(&[key.to_string()]).map_err(|e| {
            Error::new(
                ErrorKind::InvalidOperation,
                format!("Table.group_by_key: error creating grouper for key '{key}': {e}"),
            )
        })?;

        // Each vec contains the row indices for each group.
        let mut groups: Vec<Vec<u64>> = Vec::new();
        for (row_idx, group_id) in grouper.iter().enumerate() {
            match group_id.cmp(&groups.len()) {
                Ordering::Less => groups[group_id].push(row_idx as u64),
                Ordering::Equal => groups.push(vec![row_idx as u64]),
                Ordering::Greater => {
                    // SAFETY: new group ids are always created with increments of 1, so
                    // we either see a new group id equal to the current length of groups,
                    // or an existing group in this loop
                    unsafe { unreachable_unchecked() }
                }
            }

View on GitHub (pinned to 0267ce9170)