OpenTofu provider mirror configuration errors in CI

To serve providers without hitting registry.opentofu.org, OpenTofu reads a provider_installation block from its CLI config. If tofu still queries the network, the config path or block is not being picked up in CI.

What this error means

tofu init still contacts the registry despite a configured mirror, or fails with "no available releases match" because the filesystem_mirror directory layout or network_mirror URL is wrong.

tofu

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider
registry.opentofu.org/hashicorp/aws: the local package directory
"/opt/providers" does not contain a valid provider mirror layout.

Common causes

The CLI config file was not found

OpenTofu reads .tofurc or the file named by TF_CLI_CONFIG_FILE. If neither is set in CI, the mirror block is never loaded.

The mirror directory layout is wrong

A filesystem_mirror needs the registry-host/namespace/name path structure; a flat directory does not satisfy it.

How to fix it

Point tofu at the mirror config explicitly

Write a provider_installation block with the mirror method.
Set TF_CLI_CONFIG_FILE in the job env so tofu loads it.
Ensure the mirror directory uses the host/namespace/name layout.

.github/workflows/ci.yml

env:
  TF_CLI_CONFIG_FILE: ${{ github.workspace }}/.tofurc

Use the correct mirror block

Declare either a network or filesystem mirror with the exclusive include list so tofu resolves providers there instead of the public registry.

.tofurc

provider_installation {
  filesystem_mirror {
    path    = "/opt/providers"
    include = ["registry.opentofu.org/*/*"]
  }
}

How to prevent it

Set TF_CLI_CONFIG_FILE in CI so the mirror config always loads.
Populate mirrors with the correct host/namespace/name layout.
Test tofu init against the mirror before relying on it in CI.