weaviate/weaviate · warning

query maximum results exceeded: the total limit calculated f

Error message

query maximum results exceeded: the total limit calculated from the provided offset '%d' and limit '%d' exceeds the configured value for QUERY_MAXIMUM_RESULTS '%d'. If you've supplied a negative offset or limit, this may be an underflow error

What it means

localOffsetLimit guards the QUERY_MAXIMUM_RESULTS limit: if offset + limit exceeds the configured maximum for a query, the request is rejected with this explanatory message. The note about negative offset/limit exists because integer underflow can inflate the computed total, so a negative input can also trip this check. This is a deliberate guard against unbounded result materialization, not a bug.

Source

Thrown at usecases/objects/get.go:245

	return int(offset)
}

func (m *Manager) localLimitOrGlobalLimit(offset int64, paramMaxResults *int64) int {
	limit := int64(m.config.Config.QueryDefaults.Limit)
	// Get the max results from params, if exists
	if paramMaxResults != nil {
		limit = *paramMaxResults
	}

	return int(limit)
}

func (m *Manager) localOffsetLimit(paramOffset *int64, paramLimit *int64) (int, int, error) {
	offset := m.localOffsetOrZero(paramOffset)
	limit := m.localLimitOrGlobalLimit(int64(offset), paramLimit)

	if int64(offset+limit) > m.config.Config.QueryMaximumResults {
		return 0, 0, fmt.Errorf(
			"query maximum results exceeded: the total limit calculated from the provided offset '%d' and limit '%d' exceeds the configured value for QUERY_MAXIMUM_RESULTS '%d'. If you've supplied a negative offset or limit, this may be an underflow error",
			offset, limit, m.config.Config.QueryMaximumResults)
	}

	return offset, limit, nil
}

func (m *Manager) trackUsageSingle(res *search.Result) {
	if res == nil {
		return
	}
	m.metrics.AddUsageDimensions(res.ClassName, "get_rest", "single_include_vector", res.Dims)
}

func (m *Manager) trackUsageList(res search.Results) {
	if len(res) == 0 {
		return
	}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Reduce offset and/or limit so offset+limit stays within QUERY_MAXIMUM_RESULTS
2. Never send negative limit; paginate with a cursor (GraphQL withLimit/after autoCursor or sort+limit pages) instead of large offsets
3. Raise QUERY_MAXIMUM_RESULTS in the server config if the workload genuinely needs more results per query
4. Clamp/validate offset and limit in client code before issuing the query

Example fix

// before: deep offset pagination
for page := 0; ; page++ {
  offset := page * 100000 // exceeds QUERY_MAXIMUM_RESULTS
  ...
}
// after: bounded cursor pagination
limit := int64(100)
for {
  res, _ := queryObjects(ctx, after, limit) // cursor-based, offset always 0
  if len(res) < int(limit) { break }
  after = lastCursor(res)
}

const QUERY_MAXIMUM_RESULTS = 10000;
function assertPagination(offset, limit) {
  if (offset < 0 || limit <= 0) throw new Error('negative/zero offset or limit');
  if (offset + limit > QUERY_MAXIMUM_RESULTS) {
    throw new Error(`offset+limit ${offset+limit} exceeds QUERY_MAXIMUM_RESULTS`);
  }
}

try {
  assertPagination(offset, limit);
  return await client.graphql.get().withClassName('Article').withOffset(offset).withLimit(limit).do();
} catch (e) {
  if (String(e).includes('QUERY_MAXIMUM_RESULTS')) {
    return paginateWithCursor(e); // fall back to cursor pagination
  } else throw e;
}

When it happens

Trigger: GraphQL Get/nearText queries or REST list calls (getObjectsFromRepo / inputs) where client-supplied offset + limit (or a negative value that underflows) exceeds the server's QUERY_MAXIMUM_RESULTS setting.

Common situations: Deep pagination with large offsets (offset=100000); client passing limit=-1 expecting 'unlimited'; defaults after upgrading where QUERY_MAXIMUM_RESULTS was lowered; pagination loops that increment offset past the cap.

Related errors

• invalid params, pagination object is nil
• invalid pagination params: %w
• invalid params, pagination object is nil
• invalid pagination params
• date aggregator state missing from remote shard result, the

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/1322dbf4f048f3f3. Report an issue: GitHub.