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

Validate and reinstall the GD extension (php -m, reinstall php-gd), restart all PHP processes (php-fpm, Apache, phd daemons).

phacility/phabricator · error · Exception

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

Error message

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

What it means

The GD function imagecolorallocatealpha($img, 255, 255, 255, 127) returned false while newEmptyImage() tried to allocate the fully transparent white color used to fill the new canvas. GD returns false only when allocation fails (palette exhausted on palette images, or a broken resource); since the canvas is freshly created truecolor, this points at a broken GD environment rather than the color values themselves.

Source

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

    }

    $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);
    $errors = $trap->getErrorsAsString();
    $trap->destroy();
    if ($ok === false) {
      throw new Exception(
        pht(
          'Unable to imagefill() a new empty image: %s',
          $errors));
    }

    return $img;
  }

View on GitHub (pinned to 5720a38cfe)

Solutions

Validate and reinstall the GD extension (php -m, reinstall php-gd), restart all PHP processes (php-fpm, Apache, phd daemons).
Pin a known-good PHP/GD combination if it appeared after an upgrade.
Wrap transform execution in try/catch with a fallback to the untransformed file while diagnosing the environment.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  $transformed = $transform->execute($file);
} catch (Exception $ex) {
  $transformed = $file;
}

Prevention

Smoke-test the GD install (allocate + fill a tiny truecolor image) as part of deployment checks.
Reinstall php-gd and restart php-fpm/phd after any PHP packaging change.
Log the trapped $errors string from the message — it names the underlying PHP warning.

When it happens

Trigger: Reached on every newEmptyImage() call immediately after imagesavealpha(); throws only if imagecolorallocatealpha() reports failure, which stock GD on a valid truecolor image essentially never does.

Common situations: Same class as the other GD-step failures in newEmptyImage(): a miscompiled or truncated GD extension, a PHP/GD version mismatch after an upgrade, or resource corruption; not caused by user upload content.

Related errors

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