Fix PHP Fatal error: Call to undefined function imagecreatetruecolor() - Missing GD Extension

The Problem

You are likely trying to process an image—perhaps resizing a profile picture, generating a captcha, or creating a thumbnail—when your script crashes with the following error:

PHP Fatal error: Uncaught Error: Call to undefined function imagecreatetruecolor()

This happens because imagecreatetruecolor() is part of the GD (Graphics Draw) extension. If this extension is not installed or enabled in your php.ini, PHP does not recognize the function. This is a common issue on fresh server setups or when migrating to a new PHP version where extensions aren't carried over automatically.

Root Cause

The GD library is a requirement for most PHP image manipulation libraries (like Intervention Image or Imagine). By default, many Linux distributions and minimal Docker images do not include GD to keep the installation lightweight. Without the GD extension, any call to imagecreatetruecolor(), imagecreatefromjpeg(), or imagepng() will fail.

Fix for Ubuntu / Debian

On Debian-based systems, you need to install the specific GD package for your PHP version. Replace 8.x with your current version (e.g., 7.4, 8.1, 8.2, 8.3).

# Update package list
sudo apt update

# Install the GD extension (example for PHP 8.2)
sudo apt install php8.2-gd

After installation, restart your web server or PHP-FPM process to apply the changes:

# If using Apache
sudo systemctl restart apache2

# If using Nginx with PHP-FPM
sudo systemctl restart php8.2-fpm

Fix for CentOS / RHEL / AlmaLinux

For RHEL-based systems using the yum or dnf package manager:

# Install GD extension
sudo dnf install php-gd

# Restart PHP-FPM
sudo systemctl restart php-fpm

Fix for Docker (PHP-FPM Images)

If you are using the official PHP Docker images, simply using apt install inside the container isn't enough because the extension needs to be configured and enabled within the PHP environment. Use the helper script docker-php-ext-install.

Add this to your Dockerfile:

FROM php:8.2-fpm

# Install dependencies for GD
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev

# Configure and install GD
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd

Note: Modern PHP versions (7.4+) require the --with-freetype and --with-jpeg flags during configuration if you need support for those specific formats.

Fix for Windows (XAMPP / WAMP)

If you are developing locally on Windows, the GD extension is usually included but disabled by default.

• Locate your php.ini file (In XAMPP, it is usually in C:\xampp\php\php.ini).
• Open the file in a text editor and search for extension=gd.
• Remove the semicolon (;) at the beginning of the line to uncomment it:

;extension=gd --> change to --> extension=gd

  
  - Save the file and restart your Apache service via the XAMPP/WAMP Control Panel.

## Verifying the Fix
Once you have restarted your server, you should verify that the extension is active. You can do this via the command line or a web script.

### Method 1: Command Line (CLI)
Run the following command to see if "gd" appears in the list of loaded modules:

php -m | grep -i gd

If it outputs `gd`, the extension is successfully loaded for the CLI.

### Method 2: PHP Info
Create a temporary file named `info.php` in your web directory with the following content:

Access this file through your browser (e.g., `http://localhost/info.php`) and search for the "gd" section. It should show "GD Support => enabled".

## Prevention and Best Practices
To avoid this error in the future, especially when deploying to production, follow these practices:

  - **Check Composer Dependencies:** If you use a library like `intervention/image`, ensure it is listed in your `composer.json`. You can also require the extension explicitly in `composer.json` so that `composer install` fails if the extension is missing:
    ```
"require": {
    "ext-gd": "*"
}

• Environment Parity: Ensure your local development environment (XAMPP/Docker) matches your production server's PHP extensions.
• Automated Provisioning: Use scripts (Ansible, Docker, or Bash) to set up servers so that required extensions like gd, mbstring, and pdo are always installed by default.