diff --git a/docs/guides/live-queries.md b/docs/guides/live-queries.md
index b69689e16..2f6054daa 100644
--- a/docs/guides/live-queries.md
+++ b/docs/guides/live-queries.md
@@ -1048,9 +1048,12 @@ const departmentStats = createCollection(liveQueryCollectionOptions({
 > In `groupBy` queries, the properties in your `select` clause must either be:
 > - An aggregate function (like `count`, `sum`, `avg`)
 > - A property that was used in the `groupBy` clause
-> 
+>
 > You cannot select properties that are neither aggregated nor grouped.
 
+> [!WARNING]
+> `fn.select()` cannot be used with `groupBy()`. The `groupBy` operator needs to statically analyze the `select` clause to discover which aggregate functions (`count`, `sum`, `max`, etc.) to compute for each group. Since `fn.select()` is an opaque JavaScript function, the compiler cannot inspect it. Use the standard `.select()` API when combining with `groupBy()`.
+
 ### Multiple Column Grouping
 
 Group by multiple columns by returning an array from the callback:
@@ -1890,6 +1893,9 @@ The functional variant API provides an alternative to the standard API, offering
 
 ### Functional Select
 
+> [!WARNING]
+> `fn.select()` cannot be used with `groupBy()`. The `groupBy` operator needs to statically analyze the `select` clause to discover which aggregate functions to compute, which is not possible with an opaque JavaScript function. Use the standard `.select()` API for grouped queries.
+
 Use `fn.select()` for complex transformations with JavaScript logic:
 
 ```ts
diff --git a/docs/reference/classes/BaseQueryBuilder.md b/docs/reference/classes/BaseQueryBuilder.md
index b834a3876..d37bb018d 100644
--- a/docs/reference/classes/BaseQueryBuilder.md
+++ b/docs/reference/classes/BaseQueryBuilder.md
@@ -102,7 +102,8 @@ select<TFuncSelectResult>(callback): QueryBuilder<WithResult<TContext, TFuncSele
 ```
 
 Select fields using a function that operates on each row
-Warning: This cannot be optimized by the query compiler
+Warning: This cannot be optimized by the query compiler.
+Cannot be used with `groupBy()` — use the standard `.select()` API for grouped queries.
 
 ###### Type Parameters