Batchable Apex QueryLocator 50k Record Limit: Local Success vs Production Failure

The Root Cause

The 50,000-record limit is not a restriction of Database.getQueryLocator itself, but a standard SOQL governor limit. When a batch job fails in production with a "Too many query rows: 50001" exception while succeeding in a scratch org, it is almost always because the start method is returning a List<SObject> instead of a Database.QueryLocator.

Confirmed Facts vs. Likely Explanations

Confirmed Facts:

• Database.getQueryLocator is specifically designed to bypass the 50,000-record limit, allowing a batch job to process up to 50 million records.
• The 50,000-record limit is a hard governor limit for standard synchronous SOQL queries and queries that return a List.

Likely Explanation for Environment Discrepancy:

Scratch orgs often contain smaller datasets. If your scratch org has 40,000 records, a List return type will work perfectly. Once deployed to production where the dataset exceeds 50,000, the same code triggers a LimitException. This creates the illusion that the environment is enforcing the limit differently, when in reality, the data volume has simply crossed the threshold.

Required Implementation Steps

To resolve this, ensure your start method is implemented as follows:

public Database.QueryLocator start(Database.BatchableContext bc) {
    // Correct: Returns a QueryLocator, bypassing the 50k limit
    return Database.getQueryLocator('SELECT Id FROM Account');
}

Avoid this pattern:

public Iterable<SObject> start(Database.BatchableContext bc) {
    // Incorrect: This executes a standard SOQL query and returns a List,
    // which is capped at 50,000 records.
    return [SELECT Id FROM Account];
}

Verification and Diagnostics

To verify the failure in production, check the Apex Debug Logs. A LimitException: Too many query rows: 50001 confirms that a standard SOQL query was used instead of a QueryLocator.

One missing diagnostic detail: Are you using a custom Iterable implementation in your start method? If you are manually iterating over a collection rather than using a SOQL string, the QueryLocator bypass does not apply.