The Code Times
Independent GitHub code analysis
CODE VERIFIED

Payload 3.92.0 Fixes MongoDB Joins With limit: 0

Payload 3.92.0 fixes MongoDB joins with limit: 0 by omitting limiting stages. See the code change, regression coverage, and remaining documentation gap.

Oct 27, 2026, 12:11 am PDT · 6 min read
Two collections feed a joined result through an adapter that omits limiting operations for a zero-limit request.

Quick Answer

Payload 3.92.0 fixes a MongoDB adapter problem affecting joins across multiple collections when a request uses limit: 0. The aggregation builder now includes its per-collection limiting stage and its merged-results slicing stage only when the join limit is positive. For the zero-limit case, it omits both operations. The official release notes, dated October 22, 2026, list the fix through PR #18855 and commit 84483a1.

The distinction matters because zero has different roles at the application and database boundaries. The pull request and regression test establish that the zero-limit request is intended to retain all matching joined documents in the tested multi-collection case. MongoDB does not accept zero as the value of an aggregation $limit stage. The fix translates that request by leaving the limiting operations out of the pipeline.

In Plain English

A Payload Join field exposes documents that refer back to another document through a relationship field. According to the Join field documentation, its result includes docs and hasNextPage; requesting a count also makes totalDocs available. A join can therefore provide related records together with information about whether more results remain.

The affected path combines related documents from multiple collections. Before this change, that path still generated a limiting stage when the requested limit was zero. PR #18855 identifies the resulting zero-valued stage as the reason MongoDB rejected the aggregation. The MongoDB operator documentation specifies a positive 64-bit integer for $limit, explaining the mismatch.

Payload’s documentation explicitly says that setting defaultLimit: 0 returns all related documents. Its query-option table describes limit as a maximum number of related documents but does not explicitly explain zero there. For the query-level behavior discussed in this article, the evidence comes from the pull request and its added regression test. Keeping those sources separate avoids attributing a more specific promise to the documentation than it currently makes.

Code Evidence

The merged diff changes packages/db-mongodb/src/utilities/buildJoinAggregation.ts and adds coverage in test/joins/int.spec.ts. The implementation has two relevant guards: one controls the per-collection stage, and the other controls the later slice of the combined results.

The per-collection stage

The following shortened source excerpt shows the new conditional spread and the existing limit expression it protects. The omitted portion contains the stage object; this is an excerpt, not a complete replacement block.

...(limitJoin > 0
  ? [ /* stage object omitted */ ]
  : [])

// Existing expression inside that stage:
$limit: page ? page * limitJoin : limitJoin

The observed code fact is that the stage is now included only for a positive join limit. The expression that calculates its value remains inside that guard. The fix therefore changes whether the operation exists in the pipeline, while retaining the existing expression for the positive-limit path.

Code-delta diagram showing positive-limit guards around the per-collection limit and merged-results slice.
The changed builder includes both limiting operations only when the join limit is positive; a zero limit omits both.

The merged-results slice

The second guard surrounds the operation that pushes a $set stage containing $slice onto the aggregation. This editorial pseudocode summarizes that control flow; it is not a verbatim source excerpt or executable implementation.

// Editorial pseudocode
if (join limit is positive) {
  append the existing merged-results slice stage
}

These two edits address different points in the same aggregation. One determines whether each collection contributes a limited set of results. The other determines whether the merged document array is sliced afterward. For zero, the new code skips both. That second omission is relevant to the intended result: removing the invalid database stage alone would not fully describe how the builder handles the final combined array.

What the regression test establishes

The added integration test creates a parent and a child document in each of two collections. It calls findByID with joins.children.limit set to zero. Its assertions expect two joined documents, the expected collection/value pairs, and hasNextPage to be false. Those assertions make the intended query behavior concrete across the two child collections.

This is evidence about the test’s setup and expectations, not a claim that the test was independently run for this article. The supplied research reviewed the diff and the reported checks. It did not execute the integration test.

Why It Matters

The editorial significance is the adapter’s handling of an API convention at a database boundary. For the query-level behavior addressed here, the PR and regression test treat zero as a request to retain all matching joined documents. The adapter must express that behavior using operations the database accepts. Here, the correct translation is the absence of limiting stages. Passing the application value directly into the database operator produced an invalid aggregation.

For developers, the practical inference is narrow: a MongoDB-backed Payload application using a join across multiple collections could encounter this database error before the fix when requesting a zero limit. With the changed builder, that path retains matching results without these two truncation operations. The two-collection regression test supports that expectation, while leaving other data shapes outside its demonstrated coverage.

An unlimited result can also mean a large response when many documents match. That is an operational inference, not a measured outcome from the pull request. Applications that require predictable response sizes should use a positive limit and handle pagination. The supplied evidence contains no performance measurements, so it does not support claims about speed, memory use, or safe result sizes.

An Open Question

Should the Join field’s query-option documentation explicitly state what limit: 0 means? The documentation already explains the zero value for defaultLimit, while the pull request and test establish the query behavior addressed here. A direct statement in the query-option entry, consistent with that intended behavior, would resolve this documentation gap.

The code also uses a greater-than-zero condition, which excludes negative values from both guarded operations. That observation does not establish support for negative limits. The reported issue and regression test concern zero, and the cited documentation and pull request do not define the intended negative-limit behavior.

Scope and Limitations

PR #18855 was merged into the 3.x branch on October 21, 2026. It describes the change as a backport of PR #18813 and says the guarded behavior matches single-collection joins. The official v3.92.0 release followed on October 22 and includes this fix. Release availability is established by those release notes; this research does not establish which version any particular application has installed.

The implementation evidence concerns the MongoDB join aggregation utility and its added test. It should not be generalized to every Payload adapter, every query path, or all pagination behavior. The test covers two related documents across two child collections and the resulting pagination flag. It does not provide large-result measurements or broader pagination measurements.

The pull request reports that Prettier and the Git whitespace check passed, and that an ESLint comparison found no new diagnostics while existing test-file lint errors remained. Its reported local attempt at the targeted integration test could not start because the native Darwin ARM64 binary for [email protected] was missing. The PR page reports 346 of 348 checks passed. That is partial reported check success, not evidence that every check passed or that the blocked local test completed.

Sources