Intervention/image · error · DriverException

Failed to convert image to true color

Error message

Failed to convert image to true color

What it means

Runtime GD failure in NativeObjectDecoder::decode: the incoming GdImage is palette-based (imageistruecolor === false), imagepalettetotruecolor() was called, and it returned false — GD could not convert the image to true color. Since the library standardizes on truecolor cores with alpha, a failed conversion aborts with a DriverException. It is rare: GD conversion fails only for degenerate or broken image states.

Source

Thrown at src/Drivers/Gd/Decoders/NativeObjectDecoder.php:49

    /**
     * {@inheritdoc}
     *
     * @see DecoderInterface::decode()
     *
     * @throws InvalidArgumentException
     * @throws DriverException
     * @throws StateException
     */
    public function decode(mixed $input): ImageInterface
    {
        if (!$input instanceof GdImage) {
            throw new InvalidArgumentException('Image source must be of type ' . GdImage::class);
        }

        if (!imageistruecolor($input)) {
            $result = imagepalettetotruecolor($input);
            if ($result === false) {
                throw new DriverException('Failed to convert image to true color');
            }
        }

        imagesavealpha($input, true);

        // build image instance
        return new Image(
            $this->driver(),
            new Core([
                new Frame($input),
            ]),
        );
    }

    /**
     * Decode image from given GIF source which can be either a file path or binary data.
     *
     * Depending on the configuration, this is taken over by the native GD function

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pre-convert explicitly and handle failure yourself: if (!imageistruecolor($gd) && !imagepalettetotruecolor($gd)) { ... fallback ... }
2. Allocate at least one color in hand-built palette images (imagecolorallocate) before decoding them
3. Raise or verify memory_limit (conversion duplicates pixel data: width * height * 4 bytes) and resize very large sources first
4. If the source is a file, re-save it as truecolor PNG externally and read that instead of feeding the palette original

Example fix

// before
$gd = imagecreate(400, 300); // palette image, no colors allocated
$image = $manager->read($gd);
// DriverException: Failed to convert image to true color

// after
$gd = imagecreatetruecolor(400, 300); // start truecolor directly
$image = $manager->read($gd);

if ($gd instanceof \GdImage && !imageistruecolor($gd) && imagepalettetotruecolor($gd) === false) {
    throw new RuntimeException('Source palette image cannot be converted; re-export as truecolor');
}

try {
    $image = $manager->read($gd);
} catch (\Intervention\Image\Exceptions\DriverException $e) {
    // palette-to-truecolor failed: recreate source via imagecreatetruecolor + copy
    $truecolor = imagecreatetruecolor(imagesx($gd), imagesy($gd));
    imagecopy($truecolor, $gd, 0, 0, 0, 0, imagesx($gd), imagesy($gd));
    $image = $manager->read($truecolor);
}

When it happens

Trigger: Passing a palette (indexed-color) GdImage to the native decoder where conversion fails: images with zero colors allocated, malformed palettes from hand-built GD resources, or images whose truecolor conversion exceeds memory limits in constrained environments. Reached from read(new GdImage...) paths and internally from every GD decode that funnels a created image through NativeObjectDecoder.

Common situations: Hand-constructed GdImage objects in tests (imagecreate without imagecolorallocate); memory_limit exhaustion surfacing as a failed conversion rather than a fatal; corrupted palette images from legacy tools; edge-case monochrome/1-bit files on older GD versions.

Related errors

• Unsupported media type (MIME) ${mime}.
• Failed to read media (MIME) type from binary data
• Unable to Base64-decode image from string
• Base64-encoded data contains unsupported image type
• Failed to decode unsupported image format from binary data

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