What causes "The chunk size should be at least 1" in laravel/framework?

Pass a positive integer: ->lazy(500).

laravel/framework · error · InvalidArgumentException

The chunk size should be at least 1

Error message

The chunk size should be at least 1

What it means

InvalidArgumentException from lazy() when $chunkSize is less than 1. lazy() streams results in pages, so a non-positive chunk size is invalid; the guard rejects it up front before any query runs.

Solutions

Pass a positive integer: ->lazy(500).
Clamp the value before calling: ->lazy(max(1, (int) config('app.chunk_size', 1000))).
Validate the config value at boot and fail loudly with a clearer message if it is non-positive.

Example fix

// before
$rows = Model::lazy((int) env('CHUNK_SIZE')); // 0 when unset
// after
$rows = Model::lazy(max(1, (int) env('CHUNK_SIZE', 1000)));

Defensive patterns

Strategy: validation

Validate before calling

$chunkSize = max(1, (int) env('CHUNK_SIZE', 1000));
if ($chunkSize < 1) {
    throw new InvalidArgumentException('lazy() chunk size must be >= 1');
}
Model::lazy($chunkSize)->each($callback);

Type guard

function isValidChunkSize(int $size): bool
{
    return $size >= 1;
}

Try / catch

try {
    Model::lazy($size)->each($callback);
} catch (\InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'chunk size should be at least 1')) {
        Model::lazy(max(1, $size))->each($callback);
    }
    throw $e;
}

Prevention

Clamp env-derived chunk sizes with max(1, ...) at the call site.
Validate numeric config keys during application boot.
Default chunk sizes to a sane positive number (e.g. 1000).

When it happens

Trigger: Calling ->lazy(0), ->lazy(-1), or passing a config/computed value that evaluates to < 1 (e.g. null coalesced wrong, env var parsed as 0).

Common situations: Reading chunk size from config/env where the variable is unset and defaults to 0; dynamic sizing math that can produce 0 for small datasets; copy-paste from chunk() with a placeholder value.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/e4117061240b1cfa. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Database/Concerns/BuildsQueries.php:256

                if ($callback($value, (($page - 1) * $count) + $key) === false) {
                    return false;
                }
            }
        }, $column, $alias);
    }

    /**
     * Query lazily, by chunks of the given size.
     *
     * @param  int  $chunkSize
     * @return \Illuminate\Support\LazyCollection<int, TValue>
     *
     * @throws \InvalidArgumentException
     */
    public function lazy($chunkSize = 1000)
    {
        if ($chunkSize < 1) {
            throw new InvalidArgumentException('The chunk size should be at least 1');
        }

        $this->enforceOrderBy();

        return new LazyCollection(function () use ($chunkSize) {
            $page = 1;

            while (true) {
                $results = $this->forPage($page++, $chunkSize)->get();

                foreach ($results as $result) {
                    yield $result;
                }

                if ($results->count() < $chunkSize) {
                    return;
                }
            }

View on GitHub (pinned to e0f6eb3518)