🚨 OpenTofu Error: 'Invalid legacy provider address' — Cause, Fix, and Troubleshooting Guide

Overview

Older state written by early Terraform recorded providers with an unqualified “legacy” address like aws instead of the fully qualified registry.opentofu.org/hashicorp/aws. When OpenTofu reads such state it needs a proper source address and cannot resolve the legacy form:

Error: Invalid legacy provider address

This configuration or its associated state refers to the unqualified provider
"aws".

You must complete the Terraform 0.13 upgrade process before upgrading to later
versions, or migrate the provider address with:
  tofu state replace-provider registry.opentofu.org/-/aws registry.opentofu.org/hashicorp/aws

Symptoms

• tofu plan/init fails with Invalid legacy provider address naming an unqualified provider.
• The state references a provider as a bare name (aws, google) with a -/ namespace.
• Appears when adopting OpenTofu (or upgrading) with very old state.
• Blocks operations until the provider address in state is rewritten.

Common Root Causes

• Very old state created before Terraform 0.13’s qualified provider addresses.
• Skipped 0.13 upgrade — the legacy address was never migrated.
• Imported/merged legacy state into a modern configuration.
• State hand-edited to a bare provider name.

How to diagnose

Read which unqualified provider the error names, then inspect the state:

tofu plan 2>&1 | sed -n '1,15p'
tofu state pull | jq '.resources[].provider' | sort -u

List the legacy addresses that need rewriting:

tofu state pull | jq -r '.resources[].provider' | grep -- '/-/'

Fixes

Rewrite the provider address in state with state replace-provider, mapping the legacy form to the qualified one:

tofu state replace-provider \
  registry.opentofu.org/-/aws \
  registry.opentofu.org/hashicorp/aws

Repeat for each legacy provider the error lists (google, azurerm, etc.):

tofu state replace-provider registry.opentofu.org/-/google registry.opentofu.org/hashicorp/google

Confirm the state is clean afterward:

tofu state pull | jq -r '.resources[].provider' | sort -u
tofu plan

Back up first — pull a copy of state before rewriting:

tofu state pull > state-backup-$(date +%s).json

What to watch out for

• Always back up state before replace-provider; it rewrites every matching resource.
• Run one replace-provider per legacy provider — the error lists them one at a time.
• After migrating, re-run tofu init so the qualified provider is installed and locked.
• This is a one-time migration; once state is rewritten and committed, it will not recur.

Related

• OpenTofu Error: ‘Provider configuration not present’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Invalid provider configuration’ — Cause, Fix, and Troubleshooting Guide
• Migrating from Terraform to OpenTofu: A Practical Guide