{"record":{"id":"386e7b22ba4ee6b6","repo":"Intervention/image","slug":"the-specified-index-is-outside-of-the-range","errorCode":null,"errorMessage":"The specified index is outside of the range","messagePattern":"The specified index is outside of the range","errorType":"exception","errorClass":"AnalyzerException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Analyzers/PixelColorAnalyzer.php","lineNumber":54,"sourceCode":"    /**\n     * @throws InvalidArgumentException\n     * @throws AnalyzerException\n     */\n    protected function colorAt(ColorProcessorInterface $processor, FrameInterface $frame): ColorInterface\n    {\n        $gd = $frame->native();\n        $index = @imagecolorat($gd, $this->x, $this->y);\n\n        if (!is_int($index)) {\n            throw new InvalidArgumentException(\n                'The specified position (' . $this->x . ', ' . $this->y . ') is not within the image area',\n            );\n        }\n\n        try {\n            $colors = imagecolorsforindex($gd, $index);\n        } catch (ValueError) {\n            throw new AnalyzerException(\n                'The specified index is outside of the range',\n            );\n        }\n\n        return $processor->import($colors);\n    }\n}\n","sourceCodeStart":36,"sourceCodeEnd":62,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Analyzers/PixelColorAnalyzer.php#L36-L62","documentation":"Thrown by the GD PixelColorAnalyzer when imagecolorsforindex() raises a ValueError, meaning imagecolorat() returned a color index that does not exist in the image's color palette. The pixel coordinates were valid (a separate InvalidArgumentException covers out-of-bounds coordinates at src/Drivers/Gd/Analyzers/PixelColorAnalyzer.php:46), but the palette itself is broken or was modified between the two calls. This only affects palette-based images (GIF, 8-bit PNG); truecolor images have no palette lookup.","triggerScenarios":"Calling $image->pickColor($x, $y) or any modifier that samples pixel colors (testModify, testApply, testColorChange paths) on a GIF or palette PNG whose color table is truncated or corrupted; mixing raw GD calls (imagecolordeallocate, imagedestroy on shared palette) with Intervention Image operations on the same native GdImage.","commonSituations":"GIFs re-saved by tools that emit malformed color tables; user code holding a reference to the native GdImage and freeing/modifying its palette while Intervention Image still operates on it; edge pixels of structurally damaged files downloaded over flaky connections.","solutions":["Re-read the image from its original source (fresh ImageManager::read()) so a clean GdImage with an intact palette is built","If you manipulate the native resource via $image->core()->native(), stop deallocating colors or replacing the palette while the image object is in use","Convert the palette image to truecolor before sampling: imagepalettetotruecolor($image->core()->native())","Verify the palette manually: $index = imagecolorat($gd, $x, $y); $index >= 0 && $index < max(imagecolorstotal($gd), 1)","If the file itself is damaged, re-encode it with an external tool before processing"],"exampleFix":"// before\n$color = $image->pickColor(10, 10);\n\n// after\nuse Intervention\\Image\\Exceptions\\AnalyzerException;\n\ntry {\n    $color = $image->pickColor(10, 10);\n} catch (AnalyzerException $e) {\n    // rebuild a clean truecolor core and retry\n    $native = $image->core()->native();\n    imagepalettetotruecolor($native);\n    $color = $image->pickColor(10, 10);\n}","handlingStrategy":"try-catch","validationCode":"$gd = $image->core()->native();\n$index = @imagecolorat($gd, $x, $y);\n$total = imagecolorstotal($gd);\n// truecolor images have no palette limit ($total === 0)\n$indexOk = is_int($index) && ($total === 0 || ($index >= 0 && $index < $total));","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\AnalyzerException;\n\ntry {\n    $color = $image->pickColor($x, $y);\n} catch (AnalyzerException $e) {\n    // palette is broken: rebuild a truecolor core and retry once\n    imagepalettetotruecolor($image->core()->native());\n    $color = $image->pickColor($x, $y);\n}","preventionTips":["Do not call imagecolordeallocate or mutate palettes on native resources owned by Intervention Image","Re-read images from origin when reprocessing files that previously failed","Prefer pickColor on truecolor formats (PNG-24, JPEG, WebP) when sampling matters"],"tags":["gd","palette","pixel-color","gif","pickcolor"],"backgroundTag":"palette-index-out-of-range","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}