hashicorp/terraform · critical

unsupported protocol version

Error message

unsupported protocol version

What it means

Programmer-error panic in the provider client factory: after launching the plugin, the negotiated protocol version is neither 5 nor 6 (the only supported Terraform plugin protocol versions). The switch default panics. This means terraform launched a plugin binary that spoke an unknown protocol version.

Source

Thrown at internal/command/meta_providers.go:507

	}
}

// finalizeFactoryPlugin completes the setup of a plugin dispensed by the rpc
// client to be returned by the plugin factory.
func finalizeFactoryPlugin(rawPlugin any, protoVersion int, addr addrs.Provider, client *plugin.Client) providers.Interface {
	switch protoVersion {
	case 5:
		p := rawPlugin.(*tfplugin.GRPCProvider)
		p.PluginClient = client
		p.Addr = addr
		return p
	case 6:
		p := rawPlugin.(*tfplugin6.GRPCProvider)
		p.PluginClient = client
		p.Addr = addr
		return p
	default:
		panic("unsupported protocol version")
	}
}

func devOverrideProviderFactory(provider addrs.Provider, localDir getproviders.PackageLocalDir) providers.Factory {
	// A dev override is essentially a synthetic cache entry for our purposes
	// here, so that's how we'll construct it. The providerFactory function
	// doesn't actually care about the version, so we can leave it
	// unspecified: overridden providers are not explicitly versioned.
	log.Printf("[DEBUG] Provider %s is overridden to load from %s", provider, localDir)
	return providerFactory(&providercache.CachedProvider{
		Provider:   provider,
		Version:    getproviders.UnspecifiedVersion,
		PackageDir: string(localDir),
	})
}

// unmanagedProviderFactory produces a provider factory that uses the passed
// reattach information to connect to go-plugin processes that are already

View on GitHub (pinned to d32a084675)

Solutions

1. Upgrade or downgrade the provider to a version compatible with this Terraform release (check the provider's supported Terraform versions).
2. Upgrade Terraform itself if using a newer-protocol provider.
3. Verify the provider binary is an actual Terraform plugin (not a different executable shadowing it on PATH).

Example fix

# before
terraform { required_providers { x = { source = "...", version = "0.0.1" } } } # v4 protocol

# after
terraform { required_providers { x = { source = "...", version = ">= 2.0" } } } # v5/v6 protocol

// Pin provider versions known to speak protocol 5 or 6.
terraform {
  required_providers {
    x = { source = "...", version = ">= 2.0" }
  }
}

// Defensive client factory
defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("unsupported plugin protocol version (provider incompatible with this terraform build): %v", r)
    }
}()

When it happens

Trigger: A provider binary negotiated a protocol version outside {5,6} (e.g. an experimental v7, a very old v4, or a corrupted handshake). The rawPlugin type-assertion switch has no case for it.

Common situations: Using an extremely old or bleeding-edge provider binary incompatible with this Terraform version; mismatched terraform-plugin SDK / framework versions; a custom-built provider with a non-standard protocol.

Related errors

• found unrecognized test status:
• your version of Terraform Enterprise does not support key-va
• plugin is not supported by the remote version of Terraform E
• unsupported action trigger type: %T
• saved backend configuration is invalid: %w

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/b3e68e1903192be9. Report an issue: GitHub.