provider %s: locked version selection %s doesn't match the u

Error message

provider %s: locked version selection %s doesn't match the updated version constraints %q

What it means

Indicates the locked provider version is outside the current constraints AND the constraint string recorded in the lock file differs from the one now in the configuration. This is the 'module author changed required_providers since the last init' path: the lock is stale relative to new constraints, so the previously-selected version no longer satisfies. Distinguished from 805 specifically by currentConstraints != lockedConstraints.

Source

Thrown at internal/configs/config.go:312

			continue
		}

		selectedVersion := lock.Version()
		allowedVersions := providerreqs.MeetingConstraints(constraints)
		log.Printf("[TRACE] Config.VerifyDependencySelections: provider %s has %s to satisfy %q", providerAddr, selectedVersion.String(), providerreqs.VersionConstraintsString(constraints))
		if !allowedVersions.Has(selectedVersion) {
			// The most likely cause of this is that the author of a module
			// has changed its constraints, but this could also happen in
			// some other unusual situations, such as the user directly
			// editing the lock file to record something invalid. We'll
			// distinguish those cases here in order to avoid the more
			// specific error message potentially being a red herring in
			// the edge-cases.
			currentConstraints := providerreqs.VersionConstraintsString(constraints)
			lockedConstraints := providerreqs.VersionConstraintsString(lock.VersionConstraints())
			switch {
			case currentConstraints != lockedConstraints:
				errs = append(errs, fmt.Errorf("provider %s: locked version selection %s doesn't match the updated version constraints %q", providerAddr, selectedVersion.String(), currentConstraints))
			default:
				errs = append(errs, fmt.Errorf("provider %s: version constraints %q don't match the locked version selection %s", providerAddr, currentConstraints, selectedVersion.String()))
			}
		}
	}

	// Return multiple errors in an arbitrary-but-deterministic order.
	sort.Slice(errs, func(i, j int) bool {
		return errs[i].Error() < errs[j].Error()
	})

	return errs
}

// ProviderRequirements searches the full tree of modules under the receiver
// for both explicit and implicit dependencies on providers.
//
// The result is a full manifest of all of the providers that must be available

View on GitHub (pinned to c9def3e214)

Solutions

Run `terraform init -upgrade` to re-resolve and rewrite the lock entry under the new constraints.
If you want to keep the old version intentionally, change the constraint back to match the lock (inspect lock.VersionConstraints()).
Commit the updated .terraform.lock.hcl so teammates inherit the new selection.

Example fix

// before: constraint changed, plan fails
//   required_providers { aws = { version = "~> 4.0" } }   # config
//   lock.hcl still says version = "~> 3.0", selected 3.76

$ terraform init -upgrade
// after: lock.hcl rewritten with constraints "~> 4.0", selected 4.x

Defensive patterns

Strategy: validation

Validate before calling

// Compare each provider's lock-file constraint string against the config constraint
// before plan; if they diverge, run `terraform init -upgrade` to re-resolve.
// Tools: `terraform providers lock` / inspecting depsfile.Locks in Go.

Prevention

After any required_providers change, immediately run terraform init and commit the lock file.
Treat .terraform.lock.hcl as coupled to required_providers - change one, update the other.

When it happens

Trigger: Bumping a required_providers constraint (e.g. `~> 3.0` -> `~> 4.0`) without re-running init, pulling a module update that tightens/loosens constraints, or hand-editing the lock file so its VersionConstraints no longer match config.

Common situations: Module upgrade, provider major-version bump, constraint edited in a shared module after teammates already ran init against the old constraint.

Related errors

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/01d536550f940f41. Report an issue: GitHub.