dbt-labs/dbt-core · error · InvalidOperation

Table.group_by: {e}

Error message

Table.group_by: {e}

What it means

Thrown by `Table.group_by()` when the underlying `group_by_key` operation fails, wrapping the inner error as an InvalidOperation error with the prefix `Table.group_by:`. Grouping requires a valid key column with a consistent type; failures typically come from a missing key column, an unsupported key type, or an internal grouping error.

Source

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

                        None => unimplemented!("group_by with non-string key_name"),
                    },
                    None => "group",
                };
                let key_type = match key_type {
                    Some(ty) => match ty.downcast_object_ref::<crate::DataType>() {
                        Some(dt) => Some(dt.clone()),
                        None => {
                            // TODO: support DataType class instances
                            unimplemented!("group_by with non-string key_type")
                        }
                    },
                    None => None,
                };
                let table_set = self
                    .as_ref()
                    .group_by_key(key, key_name, key_type)
                    .map_err(|e| {
                        Error::new(ErrorKind::InvalidOperation, format!("Table.group_by: {e}"))
                    })?;
                Ok(Value::from_object(table_set))
            }
            // ```python
            // def join(self, right_table, left_key=None, right_key=None, inner=False,
            //         full_outer=False, require_match=False, columns=None):
            //     """
            //     Create a new table by joining two table's on common values. This method
            //     implements most varieties of SQL join, in addition to some unique features.
            //
            //     If :code:`left_key` and :code:`right_key` are both :code:`None` then this
            //     method will perform a "sequential join", which is to say it will join on row
            //     number. The :code:`inner` and :code:`full_outer` arguments will determine
            //     whether dangling left-hand and right-hand rows are included, respectively.
            //
            //     If :code:`left_key` is specified, then a "left outer join" will be
            //     performed. This will combine columns from the :code:`right_table` anywhere
            //     that :code:`left_key` and :code:`right_key` are equal. Unmatched rows from

View on GitHub (pinned to 0267ce9170)

Solutions

1. Read the wrapped inner message after `Table.group_by:` for the root cause
2. Verify the key column exists in the table (`key in table.column_names`)
3. Check the key column's dtype is supported for grouping
4. Select/normalize the column before grouping if its type is unusual

Example fix

// before
results = table.group_by('catgory')  # typo
// after
assert 'category' in table.column_names
results = table.group_by('category')

def ensure_group_key(table, key):
    if key not in table.column_names:
        raise ValueError(f'group key {key!r} not in {table.column_names}')

null

try:
    grouped = table.group_by(key)
except Exception as e:
    if str(e).startswith('Table.group_by:'):
        raise ValueError(f'cannot group by {key!r}: {e}') from e
    raise

When it happens

Trigger: Calling `table.group_by(key)` where `group_by_key` returns an error — e.g. the key column does not exist, the key type is unsupported for grouping, or key_name/key_type resolution fails.

Common situations: Grouping by a column name with a typo, grouping on a column removed by an earlier select, or grouping on a column whose dtype the group implementation does not support.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Table.distinct: error selecting rows: {e}
• Table.limit: {e}
• Table.distinct: {e}
• Not all tables have the same column types!
• Not all tables have the same column names!

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