Intervention/image · error · Intervention\Image\Exceptions\StateException

First frame not found in image

Error message

First frame not found in image

What it means

Thrown by Core::first() when frame(0) raises the 'Frame #0 could not be found' InvalidArgumentException, which is then wrapped in this StateException. It means the core holds zero frames, so there is no first frame to return.

Solutions

1. Guard with count($image) > 0 (or $image->core()->count()) before calling first()
2. Review slice parameters: offset must be < frame count and length >= 1
3. Do not call clear() on a core you continue to use; re-read the source instead

Example fix

// before
$frame = $image->core()->first();

// after
if ($image->count() === 0) {
    throw new RuntimeException('empty image');
}
$frame = $image->core()->first();

if ($image->count() === 0) {
    throw new RuntimeException('image has no frames');
}
$frame = $image->core()->first();

function hasFrames(ImageInterface $image): bool
{
    return $image->count() > 0;
}

use Intervention\Image\Exceptions\StateException;

try {
    $frame = $image->core()->first();
} catch (StateException $e) {
    $image = $manager->read($source); // empty core: reload
    $frame = $image->core()->first();
}

When it happens

Trigger: Calling $image->core()->first() (or APIs that fetch the base frame) on a core whose frames were all removed — e.g. a slice() that removed everything (offset beyond frame count combined with the rebuild), clear() was called, or the image was constructed around an empty Imagick object.

Common situations: Slice logic that computes an offset/length removing the whole animation; reusing an image after $core->clear(); custom code creating Imagick cores manually without adding frames; the decode path producing an empty stack from a zero-byte-ish source.

Related errors

• Last frame not found in image
• Failed to add image frame
• Failed to apply , unable to re-apply image frame
• Failed to count image frames
• Failed to iterate image frames

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/f994b63dc4a4b520. Report an issue: GitHub.

Appendix: source

Thrown at src/Drivers/Imagick/Core.php:395

        }

        return $this;
    }

    /**
     * {@inheritdoc}
     *
     * @see CollectionInterface::first()
     *
     * @throws DriverException
     * @throws StateException
     */
    public function first(): FrameInterface
    {
        try {
            return $this->frame(0);
        } catch (InvalidArgumentException $e) {
            throw new StateException('First frame not found in image', previous: $e);
        }
    }

    /**
     * {@inheritdoc}
     *
     * @see CollectableInterface::last()
     *
     * @throws DriverException
     * @throws StateException
     */
    public function last(): FrameInterface
    {
        try {
            return $this->frame($this->count() - 1);
        } catch (InvalidArgumentException $e) {
            throw new StateException('Last frame not found in image', previous: $e);
        }

View on GitHub (pinned to 5598b9e397)