A version constraint and a selected provider are different records
Terraform configuration can allow a range of provider versions, while the dependency lockfile records a selected provider version and accepted package checksums. A local workstation and a Linux CI runner should not independently choose unreviewed provider versions just because both satisfy the same broad constraint.
The dependency lockfile is also different from a remote state lock. Removing it does not resolve concurrent state ownership. This guide covers provider selection and package verification, particularly when teams use more than one operating system or architecture.
Setup: record the selection and installation source
Capture the Terraform version, provider constraints, committed lockfile and runner platform. Identify whether providers come from the origin registry or an approved mirror. Preserve the exact initialization error and avoid printing backend credentials when collecting diagnostic logs.
For a controlled CI workflow, a useful check is:
terraform init -lockfile=readonly
terraform providers
Run these in the intended reviewed configuration and environment. Initialization can access the configured backend and download providers; it is not a substitute for reviewing the configuration's remote endpoints. The readonly lockfile option helps expose an unexpected selection change rather than silently rewriting the committed record.
Illustrative incident: a workstation-generated selection misses CI needs
In this fictional example, a developer initializes through a local provider mirror and commits the resulting lockfile. A Linux runner later cannot verify the package expected for its platform. Deleting the lockfile makes the immediate error disappear but allows an unreviewed selection path.
The team checks the installation method and platform coverage instead. It uses the supported provider-lock workflow to record appropriate package checksums from the intended trusted source, then reviews the resulting file as a dependency change. This is a reproducibility exercise, not a claim that every checksum error is benign.
Troubleshooting: explain the exact disagreement
| Observation | Evidence | Question |
|---|---|---|
| CI proposes a different provider version | Constraints and committed selection | Did the runner receive the intended lockfile? |
| Checksum verification fails | Package origin, platform and lockfile | Is this the expected trusted package? |
| Only one architecture fails | Runner architecture and recorded hashes | Was the required package covered? |
| Init succeeds but plan changes unexpectedly | Provider and Terraform version comparison | Did dependency behavior change? |
Do not accept a new checksum solely because a downloaded file exists. A mismatch needs source verification. Also remember that the provider lockfile does not lock every external module version; module versioning needs its own explicit configuration and release process.
Make provider changes reviewable
Commit the lockfile with the root configuration where it belongs. When deliberately upgrading providers, review the selected versions, relevant release notes and plan output rather than letting routine initialization choose an upgrade implicitly. Use the supported multi-platform locking options when the installation method requires them.
Keep trusted mirror configuration under controlled management and distinguish an expected mirror workflow from an unknown package source. Preserve the previous dependency selection and a compatible configuration revision for rollback. A dependency rollback does not automatically reverse resources already changed by an apply.
Verification, monitoring and SOP
Reproduce initialization on the supported workstation and CI platforms, then review a plan against the intended environment. Verify that routine CI initialization does not alter the lockfile. Investigate unexpected dependency diffs as code-review events instead of automatically normalizing them away.
An internal SLO can track reproducible infrastructure validation within the supported toolchain matrix; it is not an external infrastructure availability SLA. The SOP should name approved sources, supported platforms, upgrade ownership, checksum review, plan acceptance and recovery boundaries. Monitor provider initialization failures separately from state-lock contention so responders follow the correct procedure.
See Clouvenix terraform automation for a reviewed implementation and operational handover.
Technical reference
HashiCorp dependency lockfile, HashiCorp provider locking, HashiCorp initialization. Reviewed 19 October 2026; use documentation for the installed product and release.