{"record":{"id":"4ad3bee145d32775","repo":"Intervention/image","slug":"failed-to-convert-image-to-true-color","errorCode":null,"errorMessage":"Failed to convert image to true color","messagePattern":"Failed to convert image to true color","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Decoders/NativeObjectDecoder.php","lineNumber":49,"sourceCode":"    /**\n     * {@inheritdoc}\n     *\n     * @see DecoderInterface::decode()\n     *\n     * @throws InvalidArgumentException\n     * @throws DriverException\n     * @throws StateException\n     */\n    public function decode(mixed $input): ImageInterface\n    {\n        if (!$input instanceof GdImage) {\n            throw new InvalidArgumentException('Image source must be of type ' . GdImage::class);\n        }\n\n        if (!imageistruecolor($input)) {\n            $result = imagepalettetotruecolor($input);\n            if ($result === false) {\n                throw new DriverException('Failed to convert image to true color');\n            }\n        }\n\n        imagesavealpha($input, true);\n\n        // build image instance\n        return new Image(\n            $this->driver(),\n            new Core([\n                new Frame($input),\n            ]),\n        );\n    }\n\n    /**\n     * Decode image from given GIF source which can be either a file path or binary data.\n     *\n     * Depending on the configuration, this is taken over by the native GD function","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Decoders/NativeObjectDecoder.php#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pre-convert explicitly and handle failure yourself: if (!imageistruecolor($gd) && !imagepalettetotruecolor($gd)) { ... fallback ... }","Allocate at least one color in hand-built palette images (imagecolorallocate) before decoding them","Raise or verify memory_limit (conversion duplicates pixel data: width * height * 4 bytes) and resize very large sources first","If the source is a file, re-save it as truecolor PNG externally and read that instead of feeding the palette original"],"exampleFix":"// before\n$gd = imagecreate(400, 300); // palette image, no colors allocated\n$image = $manager->read($gd);\n// DriverException: Failed to convert image to true color\n\n// after\n$gd = imagecreatetruecolor(400, 300); // start truecolor directly\n$image = $manager->read($gd);","handlingStrategy":"try-catch","validationCode":"if ($gd instanceof \\GdImage && !imageistruecolor($gd) && imagepalettetotruecolor($gd) === false) {\n    throw new RuntimeException('Source palette image cannot be converted; re-export as truecolor');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $image = $manager->read($gd);\n} catch (\\Intervention\\Image\\Exceptions\\DriverException $e) {\n    // palette-to-truecolor failed: recreate source via imagecreatetruecolor + copy\n    $truecolor = imagecreatetruecolor(imagesx($gd), imagesy($gd));\n    imagecopy($truecolor, $gd, 0, 0, 0, 0, imagesx($gd), imagesy($gd));\n    $image = $manager->read($truecolor);\n}","preventionTips":["Build GD canvases with imagecreatetruecolor() instead of imagecreate()","Allocate at least one color in any intentionally palette-based GdImage","Size memory_limit to width*height*4 bytes for large-image conversions"],"tags":["gd-driver","truecolor","palette-image","memory-limit","decoder","php-gd"],"backgroundTag":"gd-image-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}