{"record":{"id":"b1583b6bf329d6fe","repo":"hashicorp/terraform","slug":"unsupported-protocol-version-d","errorCode":null,"errorMessage":"unsupported protocol version %d","messagePattern":"unsupported protocol version (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/meta_providers.go","lineNumber":580,"sourceCode":"\t\traw, err := rpcClient.Dispense(tfplugin.ProviderPluginName)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\t// store the client so that the plugin can kill the child process\n\t\tprotoVer := client.NegotiatedVersion()\n\t\tswitch protoVer {\n\t\tcase 0, 5:\n\t\t\t// As of the 0.15 release, sdk.v2 doesn't include the protocol\n\t\t\t// version in the ReattachConfig (only recently added to\n\t\t\t// go-plugin), so client.NegotiatedVersion() always returns 0. We\n\t\t\t// assume that an unmanaged provider reporting protocol version 0 is\n\t\t\t// actually using proto v5 for backwards compatibility.\n\t\t\treturn finalizeFactoryPlugin(raw, 5, provider, client), nil\n\t\tcase 6:\n\t\t\treturn finalizeFactoryPlugin(raw, 6, provider, client), nil\n\t\tdefault:\n\t\t\treturn nil, fmt.Errorf(\"unsupported protocol version %d\", protoVer)\n\t\t}\n\t}\n}\n\n// providerFactoryError is a stub providers.Factory that returns an error\n// when called. It's used to allow providerFactories to still produce a\n// factory for each available provider in an error case, for situations\n// where the caller can do something useful with that partial result.\nfunc providerFactoryError(err error) providers.Factory {\n\treturn func() (providers.Interface, error) {\n\t\treturn nil, err\n\t}\n}\n\n// providerPluginErrors is an error implementation we can return from\n// Meta.providerFactories to capture potentially multiple errors about the\n// locally-cached plugins (or lack thereof) for particular external providers.\n//","sourceCodeStart":562,"sourceCodeEnd":598,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/meta_providers.go#L562-L598","documentation":"After an unmanaged provider client is created and connected, providerFactoriesFromLocks/finalizeFactoryPlugin switches on client.NegotiatedVersion(). Only 0, 5, and 6 are handled; any other negotiated protocol falls through to this error. Unlike 726 (which fires before connecting), this fires after a successful handshake but on a protocol the runtime cannot wrap.","triggerScenarios":"TF_REATTACH_PROVIDERS points at a running provider server whose gRPC handshake negotiated a protocol version other than 5 or 6 (e.g. a future protocol 7, or a misreported value). NegotiatedVersion() returns that value after client.Client()/Dispense succeed.","commonSituations":"Provider built against a newer terraform-plugin-go than the CLI supports; provider built against an experimental protocol; stale running provider process from an older dev session still bound to the reattach socket.","solutions":["Kill the old provider process referenced by TF_REATTACH_PROVIDERS and restart the one matching the current CLI build.","Upgrade the Terraform/OpenTofu CLI to a version that supports the negotiated protocol, or downgrade the provider to proto 5/6.","Clear TF_REATTACH_PROVIDERS from the environment when not actively debugging.","Verify terraform-plugin-go / terraform-plugin-framework versions in the provider's go.mod match a supported protocol."],"exampleFix":"# before: provider negotiates proto 7\n# after: rebuild provider against framework v1.x (proto 6)\ngo get github.com/hashicorp/terraform-plugin-framework@latest\ngo build && rerun the provider harness","handlingStrategy":"validation","validationCode":"// After connecting, gate on NegotiatedVersion before using the provider.\nif v := client.NegotiatedVersion(); v != 0 && v != 5 && v != 6 {\n    return fmt.Errorf(\"negotiated protocol %d unsupported by this build\", v)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Match CLI and provider protocol generations (use proto 6 framework providers with modern Terraform).","Kill stale provider processes from previous dev sessions before reattaching.","Avoid TF_REATTACH_PROVIDERS outside development."],"tags":["terraform","provider","plugin","protocol","debugging","reattach"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}