hashicorp/terraform · error

unsupported protocol version %d

Error message

unsupported protocol version %d

What it means

Returned by unmanagedProviderFactory after the go-plugin client negotiates a version with the reattached provider and client.NegotiatedVersion() yields a value that is not 0, 5, or 6. Unlike error 721 (which checks the configured ProtocolVersion before connecting), this fires after the live handshake, meaning the running provider process actually advertises an unsupported protocol. It indicates a real incompatibility with the process Terraform connected to.

Source

Thrown at internal/command/meta_providers.go:580

		raw, err := rpcClient.Dispense(tfplugin.ProviderPluginName)
		if err != nil {
			return nil, err
		}

		// store the client so that the plugin can kill the child process
		protoVer := client.NegotiatedVersion()
		switch protoVer {
		case 0, 5:
			// As of the 0.15 release, sdk.v2 doesn't include the protocol
			// version in the ReattachConfig (only recently added to
			// go-plugin), so client.NegotiatedVersion() always returns 0. We
			// assume that an unmanaged provider reporting protocol version 0 is
			// actually using proto v5 for backwards compatibility.
			return finalizeFactoryPlugin(raw, 5, provider, client), nil
		case 6:
			return finalizeFactoryPlugin(raw, 6, provider, client), nil
		default:
			return nil, fmt.Errorf("unsupported protocol version %d", protoVer)
		}
	}
}

// providerFactoryError is a stub providers.Factory that returns an error
// when called. It's used to allow providerFactories to still produce a
// factory for each available provider in an error case, for situations
// where the caller can do something useful with that partial result.
func providerFactoryError(err error) providers.Factory {
	return func() (providers.Interface, error) {
		return nil, err
	}
}

// providerPluginErrors is an error implementation we can return from
// Meta.providerFactories to capture potentially multiple errors about the
// locally-cached plugins (or lack thereof) for particular external providers.
//

View on GitHub (pinned to c9def3e214)

Solutions

  1. Verify the PID in TF_REATTACH_PROVIDERS is still the intended provider process and restart it.
  2. Rebuild the provider against an SDK/terraform-plugin-go whose protocol version this Terraform CLI supports (5 or 6).
  3. Use a Terraform CLI version that supports the negotiated protocol version.

Example fix

// before: reattached process negotiated an unknown protocol
// after: rebuild provider with matching SDK, e.g.
$ go get github.com/hashicorp/terraform-plugin-go@<compatible-tag>
$ go build && # restart the provider, re-export TF_REATTACH_PROVIDERS
Defensive patterns

Strategy: validation

Validate before calling

// Sanity-check the reattached provider process is alive and is the intended binary before Terraform runs
package main

func assertReattachProcessAlive(pid int, expectedBinary string) error {
	p, err := os.FindProcess(pid)
	if err != nil { return fmt.Errorf("reattach pid %d not found: %w", pid, err) }
	if err := p.Signal(syscall.Signal(0)); err != nil {
		return fmt.Errorf("reattach pid %d not running: %w", pid, err)
	}
	return nil
}

Prevention

When it happens

Trigger: TF_REATTACH_PROVIDERS points at a running provider server whose go-plugin handshake reports a protocol major version outside {0,5,6}. Reached only after client.Client() and Dispense succeed, in the final switch on protoVer.

Common situations: The reattached process is not actually a Terraform provider (wrong PID reused); a custom/forked provider implemented an experimental protocol; the provider binary was built against a newer terraform-plugin-go that negotiated a higher version than this CLI knows.

Related errors

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