What causes "Failed to iterate image frames" in Intervention/image?

Never remove or slice frames inside a foreach over the same image; collect changes first, apply after the loop

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

Failed to iterate image frames

Error message

Failed to iterate image frames

What it means

Thrown by Core::current() (the SPL Iterator implementation) when setIteratorIndex() or Imagick::current() fails while the foreach loop requests the frame at the internal iterator position. Both ImagickException and the library's RuntimeException are wrapped into this DriverException.

Source

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

            throw new DriverException('Failed to count image frames', previous: $e);
        }
    }

    /**
     * {@inheritdoc}
     *
     * @see Iterator::rewind()
     *
     * @throws DriverException
     */
    public function current(): mixed
    {
        try {
            $this->imagick->setIteratorIndex($this->iteratorIndex);

            return new Frame($this->imagick->current());
        } catch (ImagickException | RuntimeException $e) {
            throw new DriverException('Failed to iterate image frames', previous: $e);
        }
    }

    /**
     * {@inheritdoc}
     *
     * @see Iterator::rewind()
     */
    public function next(): void
    {
        $this->iteratorIndex += 1;
    }

    /**
     * {@inheritdoc}
     *
     * @see Iterator::rewind()
     */

View on GitHub (pinned to 5598b9e397)

Solutions

Never remove or slice frames inside a foreach over the same image; collect changes first, apply after the loop
Check $e->getPrevious() to distinguish ImagickException (native failure) from RuntimeException (index invalid)
Re-read the image and iterate a fresh copy when resuming after partial processing
Use $image->core()->frame($i) with an explicit index instead of the iterator when you need stable positions

Example fix

// before: mutating while iterating
foreach ($image as $i => $frame) {
    $image->sliceAnimation($i, 1); // invalidates iterator
}

// after: copy first, then mutate
$snapshot = $manager->read((string) $image->toGif());
foreach ($snapshot as $i => $frame) {
    // safe: mutation happens on $image elsewhere
}

Defensive patterns

Strategy: try-catch

Try / catch

use Intervention\Image\Exceptions\DriverException;

try {
    foreach ($image as $frame) {
        process($frame);
    }
} catch (DriverException $e) {
    // iterator state is invalid; fall back to indexed access
    for ($i = 0, $n = $reloaded->count(); $i < $n; $i++) {
        process($reloaded->core()->frame($i));
    }
}

Prevention

Never remove/slice frames inside a foreach over the same image
Prefer indexed frame($i) loops when you mutate the animation
Do not share one Image between parallel workers or coroutines

When it happens

Trigger: Iterating an Imagick core: foreach ($image as $frame) or foreach ($image->core() as $frame), or calling current()/get() explicitly. It fires when the iterator index no longer points at a valid frame — typically because frames were removed (slice/removeImage) during iteration, or the Imagick object was destroyed mid-loop.

Common situations: Modifying an animation while looping over it (removing frames inside foreach); long loops where the underlying resource times out or is freed; running array operations that partially consume the iterator then resuming; concurrent access to the same Imagick object from coroutines/parallel workers.

Related errors

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