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.

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.

Appendix: 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)