⚙️ OpenTofu Error: 'Unsupported provider plugin protocol version' mismatch

Exact Error Message

╷
│ Error: Unsupported provider plugin protocol version
│
│ Provider "registry.opentofu.org/hashicorp/aws" version 3.75.0 uses plugin
│ protocol version 4, which is no longer supported by OpenTofu; this provider
│ must be updated to a newer version to work with this version of OpenTofu.
╵

A locally built or misinstalled plugin can also produce:

│ Error: Incompatible API version with plugin. Plugin version: 4, Client versions: [5 6]

What It Means

OpenTofu talks to providers over a versioned gRPC plugin protocol. Modern OpenTofu speaks protocol versions 5 and 6. When a provider binary advertises a protocol version OpenTofu no longer supports (typically the old protocol 4 used by very old providers), the handshake fails and OpenTofu refuses to load the plugin.

This is a compatibility boundary, not a network or checksum problem. Either the provider is too old for your OpenTofu, or a manually placed/dev-built plugin binary was compiled against the wrong plugin SDK.

Common Causes

• A pinned provider version that predates protocol 5 (very old hashicorp/aws, hashicorp/azurerm, etc.).
• A dev-overridden provider (dev_overrides in .tofurc) built against an incompatible plugin SDK.
• A hand-placed plugin binary in the local mirror/plugin cache that is out of date.
• An in-house/custom provider that has not been rebuilt against the current terraform-plugin-go/SDK.
• Mixing a very new OpenTofu with an ancient provider lock file copied from a legacy project.

Diagnostic Commands

Check your OpenTofu version:

tofu version

List the provider versions currently selected:

tofu providers

Ask a suspect provider binary directly which protocol it speaks:

~/.terraform.d/plugins/registry.opentofu.org/hashicorp/aws/3.75.0/linux_amd64/terraform-provider-aws_v3.75.0 --help

Re-run init with debug logging to see the handshake:

TF_LOG=trace tofu init 2>&1 | grep -i "protocol\|plugin"

Step-by-Step Resolution

1. Identify which provider and version is failing. The error names both. Confirm the pinned constraint in your config:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.75"   # too old — uses protocol 4
    }
  }
}

2. Raise the constraint to a version that speaks protocol 5 or 6. Nearly all actively maintained providers do:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

3. Refresh the dependency lock and download the newer plugin:

tofu init -upgrade

4. If a stale binary is cached locally, remove the plugin cache and the lock, then re-init:

rm -rf .terraform .terraform.lock.hcl
tofu init -upgrade

5. If the failure is a custom/dev provider, rebuild it against a current plugin SDK (terraform-plugin-framework or terraform-plugin-sdk v2) so it serves protocol 5/6, then reinstall it into your local mirror.

6. Confirm the provider now loads:

tofu providers && tofu validate

provider[registry.opentofu.org/hashicorp/aws] 5.60.0

Prevention

• Track provider upgrades regularly instead of pinning to years-old major versions.
• Commit the .terraform.lock.hcl so every environment resolves the same compatible provider set.
• When you bump OpenTofu, run tofu init -upgrade and review provider constraints in the same change.
• Rebuild in-house providers against a supported plugin SDK whenever you adopt a newer OpenTofu.
• Avoid hand-placing plugin binaries; use the registry or a proper local mirror so versions stay coherent.

Related Errors

• Failed to install provider — a download/network/platform failure rather than a protocol mismatch.
• Incompatible provider version / no available provider matches constraints — version-constraint resolution, not protocol.
• checksums previously recorded do not match — a lock-file checksum mismatch after swapping binaries.
• Failed to request discovery document — the registry itself is unreachable during resolution.

Frequently Asked Questions

Which protocol versions does OpenTofu support? Current OpenTofu supports plugin protocol versions 5 and 6. Providers still on protocol 4 must be upgraded.

Can I downgrade OpenTofu to run an old provider instead? You can, but it is a dead end. Upgrade the provider to a protocol 5/6 release; almost every maintained provider already ships one.

Why does my custom provider fail but registry ones work? Your provider was likely built against an outdated plugin SDK. Rebuild it against terraform-plugin-framework or SDK v2 so it advertises protocol 5/6.

Do I need to delete .terraform to fix this? Only if a stale binary is cached. Removing .terraform and the lock file, then running tofu init -upgrade, forces a clean re-download. See the prompt library for provider-upgrade playbooks and more OpenTofu guides.