{"record":{"id":"39951b4ebc49ad17","repo":"hashicorp/packer","slug":"incompatible-api-major-version-with-plugin-plugin","errorCode":null,"errorMessage":"Incompatible API MAJOR version with plugin. plugin MINOR API version: %s, Ours: %s","messagePattern":"Incompatible API MAJOR version with plugin\\. plugin MINOR API version: (.+?), Ours: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packer/plugin_client.go","lineNumber":344,"sourceCode":"\t\tline := strings.TrimSpace(string(lineBytes))\n\t\tparts := strings.SplitN(line, \"|\", 4)\n\t\tif len(parts) == 3 {\n\t\t\t// In protocol version 4 and before, the protocol only had a Major\n\t\t\t// version\n\t\t\terr = fmt.Errorf(\"The protocol of this plugin (protocol version 4 \" +\n\t\t\t\t\"and lower) was deprecated, please use a newer version of this plugin.\" +\n\t\t\t\t\"Or use an older version of Packer (pre 1.7) with this plugin.\")\n\t\t\treturn nil, err\n\t\t}\n\t\tif len(parts) < 4 {\n\t\t\terr = fmt.Errorf(\"Unrecognized remote plugin message: %s\", line)\n\t\t\treturn nil, err\n\t\t}\n\t\tpluginMajorAPIVersion, pluginMinorAPIVersion, network, netAddr := parts[0], parts[1], parts[2], parts[3]\n\n\t\t// Test the API versions\n\t\tif pluginMajorAPIVersion != pluginsdk.APIVersionMajor {\n\t\t\terr = fmt.Errorf(\"Incompatible API MAJOR version with plugin. \"+\n\t\t\t\t\"plugin MINOR API version: %s, Ours: %s\", pluginMajorAPIVersion, pluginsdk.APIVersionMajor)\n\t\t\treturn nil, err\n\t\t}\n\t\tif pluginMinorAPIVersion > pluginsdk.APIVersionMinor {\n\t\t\terr = fmt.Errorf(\"Incompatible API MINOR version with plugin. \"+\n\t\t\t\t\"plugin MINOR API version: %s, Ours: %s. Please upgrade Packer.\", pluginMinorAPIVersion, pluginsdk.APIVersionMinor)\n\t\t\treturn nil, err\n\t\t}\n\n\t\tswitch network {\n\t\tcase \"tcp\":\n\t\t\tc.address, err = net.ResolveTCPAddr(\"tcp\", netAddr)\n\t\tcase \"unix\":\n\t\t\tc.address, err = net.ResolveUnixAddr(\"unix\", netAddr)\n\t\tdefault:\n\t\t\treturn nil, fmt.Errorf(\"Unknown address type: %s\", network)\n\t\t}\n\t\tlog.Printf(\"Received %s RPC address for %s: addr is %s\", network, cmd.Path, c.address)","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/hashicorp/packer/blob/eb36e3c3e48a036f3e8cc94087636ee72e1303c9/packer/plugin_client.go#L326-L362","documentation":"After parsing the handshake, Packer compares the plugin's major API version with its own (pluginsdk.APIVersionMajor). Major versions are incompatible by design, so a mismatch aborts the connection with this error naming both versions.","triggerScenarios":"Client.Start() in packer/plugin_client.go sees pluginMajorAPIVersion != pluginsdk.APIVersionMajor in the handshake line — the plugin was built against a different major generation of the plugin API than this Packer binary supports.","commonSituations":"Plugin built against a pre-release or future SDK major version; running a brand-new plugin with a very old Packer; running an ancient plugin with a new Packer after a major API bump.","solutions":["Upgrade Packer to a release supporting the plugin's major API version (usually the fix when plugin major > ours).","Downgrade or reinstall the plugin at a release matching your Packer's supported API major version.","Rebuild the plugin against the packer-plugin-sdk version compatible with your Packer."],"exampleFix":"// before: new plugin + old packer\n// error: Incompatible API MAJOR version with plugin. plugin MINOR API version: 1, Ours: ...\n// after\n$ packer --version           # check current version\n$ brew upgrade hashicorp/tap/packer   # or download latest release, then retry","handlingStrategy":"validation","validationCode":"// check plugin handshake major version before starting\nout, _ := exec.Command(pluginPath, \"packer-plugin\").Output()\nparts := strings.Split(strings.TrimSpace(string(out)), \"|\")\nif len(parts) >= 1 && parts[0] != pluginsdk.APIVersionMajor { /* upgrade/downgrade Packer or plugin */ }","typeGuard":null,"tryCatchPattern":"if _, err := client.Start(); err != nil {\n  if strings.Contains(err.Error(), \"Incompatible API MAJOR version\") {\n    // upgrade Packer or pick a matching plugin release\n  }\n}","preventionTips":["Keep Packer and plugins reasonably up to date together.","Pin plugin versions in required_plugins to known-compatible releases.","Check Packer release notes after major plugin API bumps."],"tags":["plugin-protocol","version-compatibility","api-version"],"backgroundTag":"plugin-api-version-mismatch","analyzedSha":"eb36e3c3e48a036f3e8cc94087636ee72e1303c9","analyzedAt":"2026-09-05T13:20:43.127Z","contentChangedAt":"2026-09-05T13:20:43.127Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}