laravel/framework · error · RuntimeException

The chunkById operation was aborted because the [{$alias}] c

Error message

The chunkById operation was aborted because the [{$alias}] column is not present in the query result.

What it means

Thrown by orderedChunkById during chunkById/eachById when the alias column used to track pagination cursor ($lastId = data_get($results->last(), $alias)) is null — meaning the selected result rows do not expose that key. Without a valid lastId the next chunk would repeat the same rows forever, so Laravel aborts.

Source

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

            if ($countResults === 0) {
                break;
            }

            if (! is_null($remaining)) {
                $remaining = max($remaining - $countResults, 0);
            }

            // On each chunk result set, we will pass them to the callback and then let the
            // developer take care of everything within the callback, which allows us to
            // keep the memory low for spinning through large result sets for working.
            if ($callback($results, $page) === false) {
                return false;
            }

            $lastId = data_get($results->last(), $alias);

            if ($lastId === null) {
                throw new RuntimeException("The chunkById operation was aborted because the [{$alias}] column is not present in the query result.");
            }

            unset($results);

            $page++;
        } while ($countResults == $count);

        return true;
    }

    /**
     * Execute a callback over each item while chunking by ID.
     *
     * @param  callable(TValue, int): mixed  $callback
     * @param  int  $count
     * @param  string|null  $column
     * @param  string|null  $alias
     * @return bool

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Include the id (or your primary key) column in the select: ->select(['id','name'])->chunkById(...).
2. Pass the correct column and alias: ->chunkById(100, $cb, 'uuid', 'uuid').
3. Call ->select('*') or omit select entirely so the key column is present.
4. For Eloquent, ensure the model's getKeyName()/primaryKey matches the column you chunk on.

Example fix

// before
Order::select('total')->chunkById(500, function ($orders) {
    // ...
});

// after
Order::select(['id','total'])->chunkById(500, function ($orders) {
    // ...
});

$alias = $alias ?? (new $model)->getKeyName();
$sample = $query->clone()->limit(1)->get([$alias]);
if (! $sample->isEmpty() && $sample->first()->{$alias} === null) {
    throw new \RuntimeException("Column {$alias} not selected; chunkById would loop");
}

function chunkColumnIsSelected(\Illuminate\Database\Eloquent\Builder $q, string $alias): bool
{
    $cols = $q->getQuery()->columns;
    return $cols === null || in_array('*', $cols, true) || in_array($alias, $cols, true);
}

try {
    $query->chunkById(500, $cb, $column, $alias);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'chunkById operation was aborted')) {
        $query->select('*')->chunkById(500, $cb, $column, $alias);
    } else throw $e;
}

When it happens

Trigger: Calling ->select('name')->chunkById(100, ...) without including the id column; using ->addSelect with a custom alias that does not match the defaultKeyName (usually 'id'); passing an $alias that does not correspond to a selected column; selecting aggregate/custom rows that drop the id.

Common situations: Optimising a query to select only specific columns and forgetting the id; using a custom primary key (uuid) without specifying $column/$alias; renaming the primary key column; Eloquent where get() returns objects without the expected attribute.

Related errors

• The lazyById operation was aborted because the [{$alias}] co
• No record found for the given query.
• $count records were found.
• The chunk size should be at least 1
• Property [{$key}] does not exist on the Eloquent builder ins

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/22d3ba1f502e4347.json. Report an issue: GitHub.