Intervention/image · error · InvalidArgumentException

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

Error message

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

What it means

A GD Frame's native core must be a GdImage object (PHP 8's GD handle object, not a resource). setNative() throws InvalidArgumentException for anything else, guarding against legacy gd resources from pre-PHP8 style code or foreign objects like Imagick instances.

Source

Thrown at src/Drivers/Gd/Frame.php:53

     *
     * @see FrameInterface::toImage()
     */
    public function toImage(DriverInterface $driver): ImageInterface
    {
        return new Image($driver, new Core([$this]));
    }

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

        $this->native = $native;

        return $this;
    }

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

View on GitHub (pinned to 5598b9e397)

Solutions

1. Build the GdImage first: imagecreatefromstring($binary) or imagecreatetruecolor($w, $h)
2. Take natives from existing GD frames via $frame->native() instead of constructing them
3. Let the driver create frames (driver->createImage(), animation factories) rather than new Frame(...)

Example fix

// before
$frame = new Frame($binaryString); // string is not a GdImage

// after
$native = imagecreatefromstring($binaryString);
$frame = new Frame($native); // GdImage instance

if (!$native instanceof GdImage) {
    $native = imagecreatefromstring($native); // binary string to GdImage
}
$frame->setNative($native);

function isGdImage(mixed $value): bool
{
    return $value instanceof GdImage;
}

try {
    $frame->setNative($native);
} catch (InvalidArgumentException $e) {
    $frame->setNative(imagecreatefromstring((string) $native));
}

When it happens

Trigger: new Frame(fopen(...)) or new Frame($binaryString) with manual frame construction; passing a raw resource left over from old GD code; mixing natives between the GD and Imagick drivers.

Common situations: Migrating Intervention Image v2 code that passed gd resources around, interoperability layers that shuttle native handles between libraries and drivers.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Color object must be of type {ColorInterface::class}
• Base64-encoded data must be either of type string or instanc
• Unsupported image source type "{type}"
• Image source must be of type SplFileInfo
• Image source must be a resource of type 'file' or 'stream'

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