How to Fix Composer’s “Could Not Find a Version Matching Your Minimum-Stability” Error

Last updated on July 22nd, 2026 at 01:36 am

Composer protects PHP projects from accidentally installing unstable dependencies. That safeguard can produce a confusing error when a package exists but has no stable version:

Could not find a version of package vendor/package matching your minimum-stability (stable).

This tutorial explains what the message means, how to diagnose it, and how to choose the safest fix whether you consume the package or maintain it.

The problem

A project commonly uses Composer’s default stable minimum stability. If the requested package has only a branch such as dev-main and no stable semantic-version tag, Composer refuses to select it automatically.

The package may be valid and publicly available. The error means that none of its available versions satisfy the consuming project’s stability rules.

How Composer determines stability

• Tags such as v1.0.0 are stable.
• Tags such as v1.0.0-beta.1 are pre-releases.
• Branches such as dev-main are development versions.

A project with no explicit minimum-stability setting accepts stable releases. This useful default prevents an unrelated development dependency from entering the project silently.

Step 1: Inspect the available versions

Ask Composer to show every known version:

composer show vendor/package --all

Replace vendor/package with the package name. If the versions list contains only dev-main or another development branch, the package does not yet have a stable release available to Composer.

If the package is distributed through a registry, also check that the registry has indexed the latest Git tags. A newly pushed tag may take a short time to appear.

Step 2: Choose the correct fix

Option A: Allow the development branch for one package

If you need to test a development-only package, allow instability for that dependency only:

composer require vendor/package:dev-main@dev

The @dev flag applies to this requirement. It is safer than lowering the minimum stability of the entire project.

For short-term reproducibility, you can target a specific commit:

composer require vendor/package:"dev-main#COMMIT_HASH"

Replace COMMIT_HASH with the intended commit. A proper tagged release is usually easier to maintain over time.

Option B: Publish a stable semantic-version tag

If you maintain the package and it is ready for stable use, create a semantic-version tag. First verify that the intended commit is tested, documented, and compatible with the version number.

git status
git log -1 --oneline
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

After the package registry processes the new tag, consumers can install it normally:

composer require vendor/package

Do not publish a stable tag merely to silence Composer. A stable version communicates a compatibility promise to users.

Option C: Publish an honest pre-release

If the package is not ready for a stable release, use an alpha, beta, or release-candidate tag:

git tag -a v1.0.0-beta.1 -m "Release v1.0.0 beta 1"
git push origin v1.0.0-beta.1

A consuming project can request it explicitly:

composer require vendor/package:"^1.0@beta"

Step 3: Verify the selected version

composer show vendor/package
composer validate

Review the changes to composer.json and composer.lock. The lock file should record the intended version or commit.

Common mistakes and troubleshooting

Lowering minimum stability globally

This workaround is broader than it appears:

{
  "minimum-stability": "dev"
}

It allows development versions throughout the dependency graph. Avoid it unless the entire project intentionally accepts that policy. Although "prefer-stable": true makes Composer prefer stable packages when available, a package-specific stability flag is more precise.

Assuming the main branch is stable

A branch named main is still exposed as dev-main. Composer needs a semantic-version tag, an explicit branch constraint, or an appropriate branch alias.

Moving a published tag

If a tagged release contains a mistake, do not silently move a tag that others may already have installed. Publish a corrected patch release, such as v1.0.1, so existing lock files remain reproducible.

The new tag is not visible yet

Confirm that the registry webhook or manual update completed. Then refresh local metadata:

composer clear-cache
composer show vendor/package --all

Conclusion

Composer’s minimum-stability error is usually a version-selection problem, not a missing-package problem. Consumers can opt into one development dependency with a package-specific stability flag. Maintainers should publish an honest semantic-version release when the package is ready. Keeping exceptions narrow preserves predictable dependency resolution for the rest of the project.

Tags:

• cli
• Composer
• git
• github