chroma-core/chroma · error · Error

MaxK keys cannot be empty

Error message

MaxK keys cannot be empty

What it means

MaxK is the 'k largest values' aggregate used in GroupBy queries. Its constructor validates that at least one key (the field to aggregate over) is provided; an empty keys array fails fast with a plain Error before the query is serialized.

Source

Thrown at clients/new-js/packages/chromadb/src/execution/expression/groupBy.ts:86

      throw new Error("MinK k must be positive");
    }
  }

  public toJSON(): AggregateJSON {
    return {
      $min_k: {
        keys: this.keys.map((key) => key.name),
        k: this.k,
      },
    };
  }
}

export class MaxK extends Aggregate {
  constructor(public readonly keys: Key[], public readonly k: number) {
    super();
    if (keys.length === 0) {
      throw new Error("MaxK keys cannot be empty");
    }
    if (k <= 0) {
      throw new Error("MaxK k must be positive");
    }
  }

  public toJSON(): AggregateJSON {
    return {
      $max_k: {
        keys: this.keys.map((key) => key.name),
        k: this.k,
      },
    };
  }
}

export interface GroupByJSON {
  keys: string[];

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Default to a meaningful key such as 'score' (K.SCORE) when the computed key list is empty
2. Validate keys.length >= 1 before constructing MaxK
3. Log the keys array at query-build time to see why it is empty

Example fix

// before
const agg = Aggregate.maxK(selectedFields.filter(Boolean), 10); // may be [] -> Error

// after
const keys = selectedFields.filter(Boolean);
const agg = Aggregate.maxK(keys.length ? keys : ["score"], 10);

const keys = selectedFields.filter(Boolean);
if (keys.length === 0) {
  throw new Error("At least one aggregate key is required (e.g. 'score')");
}
const agg = Aggregate.maxK(keys, 10);

const hasNonEmptyKeys = (keys: unknown): keys is string[] =>
  Array.isArray(keys) && keys.length > 0;

When it happens

Trigger: new MaxK([], 10); Aggregate.maxK([], 10); or GroupBy built from JSON { keys: ["cat"], aggregate: { $max_k: { keys: [], k: 10 } } }.

Common situations: Dynamically deriving aggregate keys from a metadata schema or user-selected columns and getting an empty list. Reusing a MinK code path for MaxK but passing the grouping keys (already consumed) instead of the aggregate keys.

Related errors

• MinK keys cannot be empty
• MaxK k must be positive
• GroupBy keys cannot be empty
• GroupBy requires 'keys' array
• GroupBy requires 'aggregate'

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/28cb6c6c25cffd51. Report an issue: GitHub.