phacility/phabricator · error · Exception

Unable to transform image: the imagecreatefromstring() funct

Error message

Unable to transform image: the imagecreatefromstring() function is not available. Install or enable the "gd" extension for PHP.

What it means

getImage() needs imagecreatefromstring() to decode the file, and that function does not exist because the PHP 'gd' extension is not loaded in the process running the transform. Phabricator's GD-based image transforms are therefore entirely unavailable in this environment; the message says exactly which extension to install.

Source

Thrown at src/applications/files/transform/PhabricatorFileImageTransform.php:290

    $data = $file->loadFileData();
    $this->data = $data;
    return $this->data;
  }


  /**
   * Get the GD image resource for the image being transformed.
   *
   * @return resource GD image resource.
   */
  protected function getImage() {
    if ($this->image !== null) {
      return $this->image;
    }

    if (!function_exists('imagecreatefromstring')) {
      throw new Exception(
        pht(
          'Unable to transform image: the imagecreatefromstring() function '.
          'is not available. Install or enable the "gd" extension for PHP.'));
    }

    $data = $this->getData();
    $data = (string)$data;

    // First, we're going to write the file to disk and use getimagesize()
    // to determine its dimensions without actually loading the pixel data
    // into memory. For very large images, we'll bail out.

    // In particular, this defuses a resource exhaustion attack where the
    // attacker uploads a 40,000 x 40,000 pixel PNGs of solid white. These
    // kinds of files compress extremely well, but require a huge amount
    // of memory and CPU to process.

    $tmp = new TempFile();

View on GitHub (pinned to 5720a38cfe)

Solutions

Install GD: apt-get install php-gd (Debian/Ubuntu) or yum install php-gd (RHEL), matching the PHP version, e.g. php8.2-gd.
Restart every PHP process that can run transforms: php-fpm, Apache, and the Phabricator daemons (phd restart).
Verify per-environment: php -m | grep gd for CLI, and a phpinfo() page / php-fpm check for the web SAPI, plus confirm function_exists('imagecreatefromstring').

Example fix

# before: extension missing
php -m | grep gd   # (no output)

# after
sudo apt-get install php-gd
sudo systemctl restart php8.2-fpm apache2
php -r 'var_dump(function_exists("imagecreatefromstring"));' // true

Defensive patterns

Strategy: validation

Validate before calling

if (!function_exists('imagecreatefromstring')) {
  // GD unavailable: skip transforms, serve originals, and alert ops
  return $file;
}

Type guard

function gdTransformSupportAvailable(): bool {
  return extension_loaded('gd') && function_exists('imagecreatefromstring');
}

Prevention

Install php-gd as part of the base host provisioning, not after the first failure.
Verify GD per SAPI: CLI, php-fpm, and phd daemons each load their own PHP config.
Add a deploy-time check: php -r 'exit(function_exists("imagecreatefromstring") ? 0 : 1);'

When it happens

Trigger: First request for a thumbnail/transform on a host where PHP lacks GD: php -m shows no 'gd'. Note the process that throws may be php-fpm, Apache mod_php, or a phd daemon — whichever one executes the transform worker/request — and each has its own PHP config.

Common situations: Fresh server provisioning that never installed php-gd; CLI having GD while php-fpm does not (or vice versa), so tests pass but prod fails; distro PHP upgrade dropping the extension; container images built without the gd package.

Related errors

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/8216f5f1cd6e0c0d. Report an issue: GitHub.