{"record":{"id":"b3e68e1903192be9","repo":"hashicorp/terraform","slug":"unsupported-protocol-version","errorCode":null,"errorMessage":"unsupported protocol version","messagePattern":"unsupported protocol version","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/command/meta_providers.go","lineNumber":507,"sourceCode":"\t}\n}\n\n// finalizeFactoryPlugin completes the setup of a plugin dispensed by the rpc\n// client to be returned by the plugin factory.\nfunc finalizeFactoryPlugin(rawPlugin any, protoVersion int, addr addrs.Provider, client *plugin.Client) providers.Interface {\n\tswitch protoVersion {\n\tcase 5:\n\t\tp := rawPlugin.(*tfplugin.GRPCProvider)\n\t\tp.PluginClient = client\n\t\tp.Addr = addr\n\t\treturn p\n\tcase 6:\n\t\tp := rawPlugin.(*tfplugin6.GRPCProvider)\n\t\tp.PluginClient = client\n\t\tp.Addr = addr\n\t\treturn p\n\tdefault:\n\t\tpanic(\"unsupported protocol version\")\n\t}\n}\n\nfunc devOverrideProviderFactory(provider addrs.Provider, localDir getproviders.PackageLocalDir) providers.Factory {\n\t// A dev override is essentially a synthetic cache entry for our purposes\n\t// here, so that's how we'll construct it. The providerFactory function\n\t// doesn't actually care about the version, so we can leave it\n\t// unspecified: overridden providers are not explicitly versioned.\n\tlog.Printf(\"[DEBUG] Provider %s is overridden to load from %s\", provider, localDir)\n\treturn providerFactory(&providercache.CachedProvider{\n\t\tProvider:   provider,\n\t\tVersion:    getproviders.UnspecifiedVersion,\n\t\tPackageDir: string(localDir),\n\t})\n}\n\n// unmanagedProviderFactory produces a provider factory that uses the passed\n// reattach information to connect to go-plugin processes that are already","sourceCodeStart":489,"sourceCodeEnd":525,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/meta_providers.go#L489-L525","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade or downgrade the provider to a version compatible with this Terraform release (check the provider's supported Terraform versions).","Upgrade Terraform itself if using a newer-protocol provider.","Verify the provider binary is an actual Terraform plugin (not a different executable shadowing it on PATH)."],"exampleFix":"# before\nterraform { required_providers { x = { source = \"...\", version = \"0.0.1\" } } } # v4 protocol\n\n# after\nterraform { required_providers { x = { source = \"...\", version = \">= 2.0\" } } } # v5/v6 protocol","handlingStrategy":"validation","validationCode":"// Pin provider versions known to speak protocol 5 or 6.\nterraform {\n  required_providers {\n    x = { source = \"...\", version = \">= 2.0\" }\n  }\n}","typeGuard":null,"tryCatchPattern":"// Defensive client factory\ndefer func() {\n    if r := recover(); r != nil {\n        err = fmt.Errorf(\"unsupported plugin protocol version (provider incompatible with this terraform build): %v\", r)\n    }\n}()","preventionTips":["Use provider versions compatible with your Terraform release.","Verify the provider binary is a real Terraform plugin (not a PATH collision).","Check provider docs for supported Terraform protocol versions."],"tags":["terraform","provider-plugin","protocol-version","panic","version-mismatch"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}