laravel/framework · error · InvalidArgumentException

Collection given to whereBelongsTo method may not be empty.

Error message

Collection given to whereBelongsTo method may not be empty.

What it means

Thrown by Eloquent's whereBelongsTo query scope when the EloquentCollection passed as the related argument is empty. The method needs at least one model to derive the relationship name (via class basename) and to pluck owner keys for the whereIn clause, so an empty collection is unrecoverable. It is an InvalidArgumentException signaling a caller bug rather than a data condition.

Source

Thrown at src/Illuminate/Database/Eloquent/Concerns/QueriesRelationships.php:746

     * @param  string|null  $relationshipName
     * @param  string  $boolean
     * @return $this
     *
     * @throws \InvalidArgumentException
     * @throws \Illuminate\Database\Eloquent\RelationNotFoundException
     */
    public function whereBelongsTo($related, $relationshipName = null, $boolean = 'and')
    {
        if (! $related instanceof EloquentCollection) {
            $relatedCollection = $related->newCollection([$related]);
        } else {
            $relatedCollection = $related;

            $related = $relatedCollection->first();
        }

        if ($relatedCollection->isEmpty()) {
            throw new InvalidArgumentException('Collection given to whereBelongsTo method may not be empty.');
        }

        if ($relationshipName === null) {
            $relationshipName = Str::camel(class_basename($related));
        }

        try {
            $relationship = $this->model->{$relationshipName}();
        } catch (BadMethodCallException) {
            throw RelationNotFoundException::make($this->model, $relationshipName);
        }

        if (! $relationship instanceof BelongsTo) {
            throw RelationNotFoundException::make($this->model, $relationshipName, BelongsTo::class);
        }

        $this->whereIn(
            $relationship->getQualifiedForeignKeyName(),

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Guard the call: only invoke whereBelongsTo when the collection is non-empty (if ($collection->isNotEmpty())).
2. Pass a single Model instance instead of a collection when you only have one related model.
3. Early-return or fall back to a no-op query (e.g. whereRaw('1=0')) when the input collection is empty so the intent (match nothing) is preserved.

Example fix

// before
User::whereBelongsTo($teams)->get();  // $teams may be empty

// after
User::when($teams->isNotEmpty(), fn ($q) => $q->whereBelongsTo($teams))->get();

if ($related instanceof \Illuminate\Database\Eloquent\Collection && $related->isEmpty()) {
    // skip or return empty result instead of calling whereBelongsTo
    return User::whereRaw('1=0')->get();
}
User::whereBelongsTo($related)->get();

function hasRelatedModels($related): bool {
    return $related instanceof \Illuminate\Database\Eloquent\Model
        || ($related instanceof \Illuminate\Database\Eloquent\Collection && $related->isNotEmpty());
}

try {
    User::whereBelongsTo($related)->get();
} catch (\InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'may not be empty')) {
        return collect();
    }
    throw $e;
}

When it happens

Trigger: Calling User::whereBelongsTo($emptyCollection) or ->orWhereBelongsTo($emptyCollection) where $emptyCollection is an EloquentCollection with zero items (e.g. collecting related models from another query that returned no rows).

Common situations: Passing the result of a ->get() or ->all() that may legitimately be empty (e.g. filtering by a team/role list that no user belongs to), or building a collection conditionally that ends up empty before the scope call.

Related errors

• Collection given to whereAttachedTo method may not be empty.
• Unable to create query for empty collection.
• The provided value may not be null.
• The chunkById operation was aborted because the [{$alias}] c
• No record found for the given query.

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