GitHub Actions shivammathur/setup-php "Could not find PHP version"

By Daniel Zoghalchali·Latchkey

setup-php could not provision the requested PHP. The php-version does not exist or is unsupported on the runner OS, or an extension/tool download failed transiently while building the environment.

What this error means

The setup-php step fails resolving the version or installing an extension, and later php/composer steps fail with "command not found". Re-runs succeed when the cause was a transient download.

Error: PHP version 8.9 is not supported
# or
Failed to download extension from PECL (transient network error)

Common causes

Unsupported or non-existent php-version

A version like 8.9 that has not shipped, or one not supported on the selected runner OS, cannot be resolved by setup-php.

Transient extension/tool fetch failure

Extensions and tools are downloaded during setup. A brief PECL or package-source outage fails the install even with a valid version.

How to fix it

Request a supported version

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    extensions: mbstring, intl

Retry transient downloads

1. Pin php-version to a released, supported version for your runner OS.
2. Re-run when the failure is an extension/tool download error rather than an unsupported-version error.
3. Trim the extensions list to only what the build needs.

How to prevent it

• Pin php-version to a supported release.
• Retry transient extension-download failures.
• Keep the extensions list minimal.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions