Composer "The ... file could not be downloaded" - Network Failures in CI

By Daniel Zoghalchali·Latchkey

Composer’s connection to Packagist or a package’s download URL stalled or dropped. These are transient network failures and almost always succeed on retry.

What this error means

Composer fails partway through fetching package metadata or a dist archive with "file could not be downloaded" or a curl timeout. Re-running the job usually works with no change - the hallmark of a transient network issue.

  - Downloading symfony/console (v7.1.0)
The "https://api.github.com/repos/symfony/console/zipball/abc123" file could not
be downloaded (HTTP/2 0 ): Failed to connect to api.github.com port 443
[curl error 28] Operation timed out after 30000 milliseconds

Diagnose it: platform requirements and auth

Composer resolves against the PHP version and extensions actually present, so a lockfile that installs locally can be unsatisfiable on a runner with a different PHP build.

php -v && php -m | head -30
composer diagnose
composer check-platform-reqs

# install exactly what is locked, non-interactively
composer install --no-interaction --prefer-dist --no-progress

Common causes

Transient network or mirror slowness

A brief connectivity blip, an overloaded Packagist mirror, or a slow GitHub zipball endpoint causes the download to time out. Nothing is wrong with your project.

Unauthenticated GitHub API rate limiting

Without a GitHub token, Composer hits GitHub’s low anonymous rate limit and downloads start failing with 403/timeout under load.

How to fix it

Retry and prefer dist archives

Composer retries automatically, but you can re-run the install step and prefer cached dist downloads.

composer install --no-interaction --prefer-dist
# simple retry wrapper
for i in 1 2 3; do composer install --no-interaction && break; sleep 5; done

Authenticate GitHub to avoid rate limits

Provide a token so Composer uses the authenticated, higher rate limit.

composer config --global github-oauth.github.com "$GH_TOKEN"

Cache the Composer cache between runs

Caching ~/.composer/cache (or ~/.cache/composer) means most archives are already local, so a flaky network matters far less.

- uses: actions/cache@v4
  with:
    path: ~/.cache/composer
    key: composer-${{ hashFiles('composer.lock') }}

How to prevent it

• Cache the Composer cache keyed on composer.lock.
• Provide a github-oauth token in CI to avoid anonymous rate limits.
• Use --prefer-dist so installs pull stable, cacheable archives.

Frequently asked questions

Related guides

References

• Composer documentation
• GitHub Actions documentation