Intervention/image · error · InvalidArgumentException

Value for argument setNative() "$native" must be instanceof

Error message

Value for argument setNative() "$native" must be instanceof of Imagick

What it means

Frame::setNative(mixed $native) enforces that only an Imagick instance can back an Imagick Frame (src/Drivers/Imagick/Frame.php:59-63); anything else — a GdImage, array, null, mock — throws InvalidArgumentException naming the expected class. It is a hard type barrier at the driver boundary: the Imagick driver cannot operate on another driver's core object.

Source

Thrown at src/Drivers/Imagick/Frame.php:60

     *
     * @see DriverInterface::toImage()
     */
    public function toImage(DriverInterface $driver): ImageInterface
    {
        return new Image($driver, new Core($this->native()));
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::setNative()
     *
     * @throws InvalidArgumentException
     */
    public function setNative(mixed $native): FrameInterface
    {
        if (!$native instanceof Imagick) {
            throw new InvalidArgumentException(
                'Value for argument setNative() "$native" must be instanceof of ' . Imagick::class,
            );
        }

        $this->native = $native;

        return $this;
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::native()
     */
    public function native(): Imagick
    {
        return $this->native;
    }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass an Imagick instance: new Imagick() or the value from $image->core()->native() of an Imagick-driver image
2. Standardize one driver per pipeline: create the manager with ImageManager::withDriver(Driver::Imagick)
3. Type-hint or assert the variable against Imagick before calling setNative()

Example fix

// before
$frame->setNative($gdImage); // GdImage from the GD driver

// after
if (!$native instanceof Imagick) {
    throw new InvalidArgumentException(
        'Expected Imagick instance, got ' . get_debug_type($native)
    );
}
$frame->setNative($native);

if (!$native instanceof Imagick) {
    throw new InvalidArgumentException(
        'Expected Imagick instance, got ' . get_debug_type($native)
    );
}
$frame->setNative($native);

function isImagickNative(mixed $native): bool
{
    return $native instanceof Imagick;
}

// usage
if (isImagickNative($native)) {
    $frame->setNative($native);
}

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $frame->setNative($candidate);
} catch (InvalidArgumentException $e) {
    // wrong core type; re-create from the correct driver instead of coercing
    throw new LogicException('Driver mismatch: rebuild the core with Driver::Imagick', 0, $e);
}

When it happens

Trigger: Calling $frame->setNative() with the wrong core, e.g. a GD resource from the GD driver, null after a failed decode, or a fabricated value in tests; typically code that mixes ImageManager instances configured with different drivers.

Common situations: Apps instantiating both GD and Imagick managers and swapping cores between them; migrating v2 code where ->getCore() returned varying types; test fixtures constructing frames by hand.

Related errors

• Image source must be an instance of Imagick
• Image source must be binary data of type string or instance
• Image source must be data uri scheme of type string or Inter
• Image source must be of type Intervention\Image\EncodedImage
• Image source must be of type GdImage

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