{"record":{"id":"3b10673ab6d63f3d","repo":"Intervention/image","slug":"gd-php-extension-must-be-installed-to-use-this-dri","errorCode":null,"errorMessage":"GD PHP extension must be installed to use this driver","messagePattern":"GD PHP extension must be installed to use this driver","errorType":"exception","errorClass":"MissingDependencyException","httpStatus":null,"severity":"critical","filePath":"src/Drivers/Gd/Driver.php","lineNumber":43,"sourceCode":"     *\n     * @see DriverInterface::id()\n     */\n    public function id(): string\n    {\n        return 'GD';\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::checkHealth()\n     *\n     * @codeCoverageIgnore\n     */\n    public function checkHealth(): void\n    {\n        if (!extension_loaded('gd') || !function_exists('gd_info')) {\n            throw new MissingDependencyException(\n                'GD PHP extension must be installed to use this driver',\n            );\n        }\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::createImage()\n     *\n     * @throws InvalidArgumentException\n     * @throws DriverException\n     */\n    public function createImage(int $width, int $height): ImageInterface\n    {\n        if ($width < 1 || $height < 1) {\n            throw new InvalidArgumentException('Invalid image size. Must be int<1, max>');\n        }","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Driver.php#L25-L61","documentation":"The GD driver's constructor runs checkHealth(), which verifies the gd extension is loaded and gd_info() exists, and throws MissingDependencyException otherwise. The library refuses to operate at all when its backend extension is unavailable.","triggerScenarios":"Constructing ImageManager with the GD driver (new ImageManager(GdDriver::class) or ImageManager::usingDriver(...)) on PHP without ext-gd: slim Docker images, minimal distro installs, extension commented out in php.ini, CLI and web SAPIs using different ini files.","commonSituations":"php:8.x-cli Docker images ship without gd, Debian/Ubuntu needing the php-gd package, Windows php.ini without extension=gd, works locally but fails in CI or the production container because a different PHP binary is used.","solutions":["Install the extension: apt-get install php-gd, or docker-php-ext-install gd in Docker images, then restart PHP-FPM/worker","Enable extension=gd in php.ini (Windows: extension=php_gd.dll)","Verify in the exact failing SAPI: php -m | grep gd and php -r 'var_dump(gd_info());'","If GD cannot be installed, require ext-imagick and construct the manager with the Imagick driver"],"exampleFix":"// before\n$manager = ImageManager::usingDriver(GdDriver::class); // fatal without ext-gd\n\n// after (runtime check + fallback)\n$driver = extension_loaded('gd') ? GdDriver::class : ImagickDriver::class;\n$manager = ImageManager::usingDriver($driver);\n\n// Dockerfile: RUN docker-php-ext-install gd","handlingStrategy":"validation","validationCode":"if (!extension_loaded('gd') || !function_exists('gd_info')) {\n    throw new RuntimeException('Install ext-gd or configure the Imagick driver');\n}\n$manager = ImageManager::usingDriver(GdDriver::class);","typeGuard":"function gdAvailable(): bool\n{\n    return extension_loaded('gd') && function_exists('gd_info');\n}","tryCatchPattern":"try {\n    $manager = ImageManager::usingDriver(GdDriver::class);\n} catch (MissingDependencyException $e) {\n    $manager = ImageManager::usingDriver(ImagickDriver::class);\n}","preventionTips":["Add ext-gd to composer.json require so installs fail fast","Bake docker-php-ext-install gd into Dockerfiles","Check php -m in the exact SAPI that runs the code (CLI vs FPM)"],"tags":["gd","php-extension","missing-dependency","docker"],"backgroundTag":"missing-php-extension","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}