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

Failed to apply {class}, unable to rotate image

Error message

Failed to apply {class}, unable to rotate image

What it means

rotate() exports the background color through the driver's color processor, then calls Imagick::rotateImage($background, $angle) per frame; a false return triggers this ModifierException before the follow-up setImagePage() canvas reset runs. Non-right angles grow the canvas up to the diagonal (sqrt(2) x each side for 45 degrees), so memory and ImageMagick width/height policy caps are the classic failure sources. The exception aborts mid-loop, leaving earlier frames already rotated.

Source

Thrown at src/Drivers/Imagick/Modifiers/RotateModifier.php:31

class RotateModifier extends GenericRotateModifier implements SpecializedInterface
{
    /**
     * @throws ModifierException
     * @throws StateException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        $background = $this->driver()
            ->colorProcessor($image)
            ->export($this->backgroundColor());

        foreach ($image as $frame) {
            try {
                $result = $frame->native()->rotateImage($background, $this->rotationAngle());

                if ($result === false) {
                    throw new ModifierException(
                        'Failed to apply ' . self::class . ', unable to rotate image',
                    );
                }

                // Reset the virtual canvas page that rotateImage() leaves behind. A
                // non-right angle produces a negative page offset which otherwise
                // corrupts the animated-AVIF (libheif sequences) writer, leaving the
                // bottom/right region transparent. Mirrors TrimModifier/CoverModifier.
                $frame->native()->setImagePage(0, 0, 0, 0);
            } catch (ImagickException $e) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to rotate image',
                    previous: $e,
                );
            }
        }

        return $image;

View on GitHub (pinned to 5598b9e397)

Solutions

1. Estimate the rotated canvas (diagonal = sqrt(w^2 + h^2)) and downscale first if it exceeds your limits
2. Raise PHP memory_limit and policy.xml width/height/area caps for legitimate large rotations
3. Prefer right angles (90/180/270) where the canvas does not grow
4. Inspect $e->getPrevious()?->getMessage() (null on this branch) or Imagick::getResourceLimit() when diagnosing

Example fix

// before
$image->rotate(45); // full-size 4000x3000 photo

// after
$diagonal = (int) ceil(hypot($image->width(), $image->height()));
if ($diagonal > 8000) {
    $image->resize(2000, null); // shrink before a free-angle rotate
}
$image->rotate(45);

$diagonal = (int) ceil(hypot($image->width(), $image->height()));
$maxSide = 8192; // keep below policy.xml caps and memory budget
if ($diagonal > $maxSide) {
    $scale = $maxSide / $diagonal;
    $image->resize((int) round($image->width() * $scale), (int) round($image->height() * $scale));
}
$image->rotate($angle);

use Intervention\Image\Exceptions\ModifierException;

try {
    $image->rotate(45);
} catch (ModifierException $e) {
    $msg = $e->getPrevious()?->getMessage() ?? '';
    if (str_contains($msg, 'limit') || str_contains($msg, 'memory')) {
        // canvas grew past limits: pre-downscale and retry, or reject the angle
    } else {
        throw $e;
    }
}

When it happens

Trigger: $image->rotate(45) on a large image whose rotated canvas exceeds policy.xml width/height/area limits or the PHP memory_limit; a background color whose exported native format the frame rejects.

Common situations: Free-angle rotation features on user photos (straightening sliders) in workers with tight memory; hardened shared hosts with strict ImageMagick policies; rotating already-large panoramas by odd angles.

Related errors

• Failed to apply {class}, unable to process rotation
• Failed to apply {class}, unable to pixelate image
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

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