laravel/framework · error · LogicException

Resource collection guesser expects the collection to…

Error message

Resource collection guesser expects the collection to contain objects.

What it means

Thrown by guessResourceCollection() when the collection is non-empty but its first element ($this->items[0]) is not an object. The guesser inspects the first item to derive the model class and resolve its API resource; scalar/array/null items have no class to introspect, so it throws LogicException. An empty collection short-circuits earlier and is fine.

Solutions

Pass an explicit resource class to toResourceCollection(MyResource::class).
Ensure the collection contains model objects (use Eloquent, not raw arrays).
Cast the items back to objects if appropriate, or use a manual resource mapping.

Example fix

// before
$resource = $scalarCollection->toResourceCollection();
// after
$resource = $scalarCollection->toResourceCollection(MyResource::class);

Defensive patterns

Strategy: type-guard

Validate before calling

if (! $collection->isEmpty() && ! is_object($collection->first())) {
    throw new \LogicException('Collection must contain objects for resource guessing.');
}
return $collection->toResourceCollection();

Type guard

function isObjectCollection(\Illuminate\Support\Collection $c): bool {
    return $c->isEmpty() || $c->every(fn ($i) => is_object($i));
}

Try / catch

try {
    return $collection->toResourceCollection();
} catch (\LogicException $e) {
    return $collection->toResourceCollection(\App\Http\Resources\GenericResource::class);
}

Prevention

Keep collections as Eloquent results rather than raw arrays.
Pass an explicit resource class when the source type is uncertain.
Add an explicit class-string argument to avoid guess reliance.

When it happens

Trigger: Calling ->toResourceCollection() (with no explicit class) on a collection of scalars/arrays/strings; a collection of stdObjects that was actually built from arrays; a query that returned plain arrays instead of models.

Common situations: Selecting raw DB rows as arrays, mixing map-then-resource flows, calling the resource helper on a non-Eloquent dataset, or a collection that lost its object nature through an early array cast.

Related errors

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

Appendix: source

Thrown at src/Illuminate/Collections/Traits/TransformsToResourceCollection.php:47

    }

    /**
     * Guess the resource collection for the items.
     *
     * @return \Illuminate\Http\Resources\Json\ResourceCollection
     *
     * @throws \Throwable
     */
    protected function guessResourceCollection(): ResourceCollection
    {
        if ($this->isEmpty()) {
            return new ResourceCollection($this);
        }

        $model = $this->items[0] ?? null;

        if (! is_object($model)) {
            throw new LogicException('Resource collection guesser expects the collection to contain objects.');
        }

        /** @var class-string<Model> $className */
        $className = get_class($model);

        if (! method_exists($className, 'guessResourceName')) {
            throw new LogicException(sprintf('Expected class %s to implement guessResourceName method. Make sure the model uses the TransformsToResource trait.', $className));
        }

        $useResourceCollection = $this->resolveResourceCollectionFromAttribute($className);

        if ($useResourceCollection !== null && class_exists($useResourceCollection)) {
            return new $useResourceCollection($this);
        }

        $useResource = $this->resolveResourceFromAttribute($className);

        if ($useResource !== null && class_exists($useResource)) {

View on GitHub (pinned to e0f6eb3518)