chroma-core/chroma · error · TypeError

Limit offset must be a non-negative integer

Error message

Limit offset must be a non-negative integer

What it means

Limit's constructor validates that offset is an integer >= 0 (defaulting to 0 when omitted). Negative numbers, fractional offsets (e.g. 1.5), and non-number values that survive into the check (strings like "10" from untyped callers) raise this TypeError before any query is built.

Source

Thrown at clients/new-js/packages/chromadb/src/execution/expression/limit.ts:16

export interface LimitOptions {
  offset?: number;
  limit?: number | null | undefined;
}

export type LimitInput = Limit | number | LimitOptions | null | undefined;

export class Limit {
  public readonly offset: number;
  public readonly limit?: number;

  constructor(options: LimitOptions = {}) {
    const { offset = 0, limit } = options;

    if (!Number.isInteger(offset) || offset < 0) {
      throw new TypeError("Limit offset must be a non-negative integer");
    }

    if (limit !== null && limit !== undefined) {
      if (!Number.isInteger(limit) || limit <= 0) {
        throw new TypeError("Limit must be a positive integer when provided");
      }
      this.limit = limit;
    }

    this.offset = offset;
  }

  public static from(input: LimitInput, offsetOverride?: number): Limit {
    if (input instanceof Limit) {
      return new Limit({ offset: input.offset, limit: input.limit });
    }

    if (typeof input === "number") {

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Clamp page numbers before computing offset: const offset = Math.max(0, (page - 1) * size)
2. Coerce external input: Number.isInteger(+offset) && +offset >= 0 before passing it
3. Round fractional values: Math.floor(offset)

Example fix

// before
const limit = new Limit({ offset: (page - 1) * size }); // page = 0 -> offset -20 -> TypeError

// after
const limit = new Limit({ offset: Math.max(0, (page - 1) * size) });

const page = Math.max(1, Number(req.query.page) || 1);
const size = Math.floor(Number(req.query.size) || 20);
const offset = (page - 1) * size; // always >= 0
const limit = new Limit({ offset, limit: size });

const isValidOffset = (v: unknown): v is number =>
  typeof v === "number" && Number.isInteger(v) && v >= 0;

When it happens

Trigger: new Limit({ offset: -20 }) — the classic case is offset = (page - 1) * size with page = 0 producing a negative offset. Also offset: 2.5 or offset: "10" in JavaScript callers.

Common situations: Pagination math that allows page 0 (or a default page variable of 0) making (page-1)*size negative. Offset computed from a request query parameter without validation. Dividing counts (e.g. total/8) yielding fractions fed into offset.

Related errors

• Limit must be a positive integer when provided
• MinK k must be positive
• MaxK k must be positive
• Invalid limit input
• ${message}

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