Composer Could not find package Diagnostic Guide

Guide to diagnosing Composer's 'Could not find package' error, covering spelling, repository, stability, and network causes with step‑by‑step checks and fixes.

Recognizable condition

When running composer install (or composer update) Composer aborts with an error similar to:

[ErrorException]\n  Could not find package vendor/package-name at version version-spec

Cause / diagnostic table

Possible cause	What to look for
Misspelled package name or wrong vendor	Typo in `composer.json` under `require` or `require-dev`
Repository does not expose the package	Custom repository (VCS, Path, or Packagist mirror) missing or not publishing the package
Stability flag blocks the version	Package exists only as `dev`, `alpha`, `beta` or `RC` while project stability is set to `stable`
Network or proxy issue preventing repository access	Composer cannot reach the repository URL; timeout or authentication errors may appear before the “Could not find package” message

Ordered verification steps

Confirm the exact package name and version constraint in composer.json. Use composer show --available vendor/package-name to see if Composer can locate it.
List configured repositories and stability settings: composer config --list. Look for repositories entries and the minimum-stability or prefer-stable flags.
Check whether the repository actually hosts the package. For a Packagist mirror, browse https://mirror.example.com/packages.json or run composer show --platform to see available packages.
If using a private VCS repository, verify the URL is correct and accessible: git ls-remote <repo-url>.
Test network connectivity: curl -I <repository-url> or wget --spider <repository-url>. Note any proxy environment variables (HTTP_PROXY, HTTPS_PROXY) that Composer inherits.

Fixes tied to findings

Misspelled name: Edit composer.json to correct the spelling, then run composer update vendor/package-name (or composer install).
Missing repository: Add the missing repository definition to composer.json under repositories. Example for a private Satis server:
```
{'repositories':[{'type':'composer','url':'https://satis.example.com/'}]}
```
Then run composer update.
Stability conflict: Either relax the stability requirement (minimum-stability = dev or use prefer-stable = false) or pin a specific stable version if available. For a dev version you can use 'vendor/package-name': 'dev-branch as 1.0.0' alias.
Network/proxy: Ensure HTTP_PROXY and HTTPS_PROXY are set correctly, or bypass the proxy for the repository host. If using a corporate mirror, verify SSL certificates (composer config -g cafile /path/to/ca-bundle.crt).

Escalation criteria

If after completing the verification steps and applying the appropriate fix the error persists:

Run composer diagnose to check for known environment issues.
Inspect Composer’s verbose output: composer install -vvv and look for HTTP status codes or authentication challenges.
Contact the package maintainer to confirm the package exists in the expected repository and version.
Consider opening a ticket with Composer support (GitHub issues) providing the composer.json, composer.lock (if any), and the full verbose log.

Limitations and practical verification

Older Composer releases (1.0.0) may not recognize certain repository URLs or stability flags, leading to false‑negative “Could not find package” messages. Verify you are using Composer ≥ 1.0.0 (run composer --version).

To confirm a fix works, run composer install again. Successful completion without the original error indicates resolution. Additionally, inspect the generated composer.lock file: the previously missing package should appear with the expected version constraint.

Diagnosing Composer 'Could not find package' Errors