What causes "Unable to imagesavealpha() a new empty image: %s" in phacility/phabricator?

Verify the GD install: php -i | grep -i gd, and confirm bundled GD with PNG support.

phacility/phabricator · error · Exception

Unable to imagesavealpha() a new empty image: %s

Error message

Unable to imagesavealpha() a new empty image: %s

What it means

The GD function imagesavealpha($img, true) returned false while newEmptyImage() was configuring the freshly created truecolor canvas to preserve its alpha channel. This step normally cannot fail for a valid truecolor resource, so a false return indicates a broken GD build, a corrupted image resource from an earlier step, or memory corruption-level problems rather than caller input.

Source

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

    }

    $trap = new PhutilErrorTrap();
    $img = @imagecreatetruecolor($w, $h);
    $errors = $trap->getErrorsAsString();
    $trap->destroy();
    if ($img === false) {
      throw new Exception(
        pht(
          'Unable to imagecreatetruecolor() a new empty image: %s',
          $errors));
    }

    $trap = new PhutilErrorTrap();
    $ok = @imagesavealpha($img, true);
    $errors = $trap->getErrorsAsString();
    $trap->destroy();
    if ($ok === false) {
      throw new Exception(
        pht(
          'Unable to imagesavealpha() a new empty image: %s',
          $errors));
    }

    $trap = new PhutilErrorTrap();
    $color = @imagecolorallocatealpha($img, 255, 255, 255, 127);
    $errors = $trap->getErrorsAsString();
    $trap->destroy();
    if ($color === false) {
      throw new Exception(
        pht(
          'Unable to imagecolorallocatealpha() a new empty image: %s',
          $errors));
    }

    $trap = new PhutilErrorTrap();
    $ok = @imagefill($img, 0, 0, $color);

View on GitHub (pinned to 5720a38cfe)

Solutions

Verify the GD install: php -i | grep -i gd, and confirm bundled GD with PNG support.
Reinstall/upgrade the php-gd package (apt install --reinstall php-gd or the distro equivalent) and restart php-fpm/web server plus daemons.
If it persists, capture $errors from the message and file it upstream; guard call sites with try/catch to degrade to the original image.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  $transformed = $transform->execute($file);
} catch (Exception $ex) {
  phlog($ex);
  $transformed = $file; // GD environment issue; serve original
}

Prevention

Validate GD health after PHP upgrades with a minimal imagecreatetruecolor+imagesavealpha script.
Keep PHP and php-gd versions matched; reinstall php-gd when in doubt.
Never let a transform failure break the request — always fall back to the original.

When it happens

Trigger: Any call to PhabricatorFileImageTransform::newEmptyImage() where imagecreatetruecolor() succeeded but the subsequent imagesavealpha() call fails — typically observed with mismatched/buggy GD versions or after the image resource was invalidated.

Common situations: Exotic or miscompiled GD builds (e.g. partial PHP packages where GD is present but incomplete); upgrading PHP/GD and hitting a regression; extremely rare in stock distro PHP where this call succeeds unconditionally on truecolor images.

Related errors

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