{"record":{"id":"0c2b42c87b3bf6ea","repo":"hashicorp/packer","slug":"incompatible-api-minor-version-with-plugin-plugin","errorCode":null,"errorMessage":"Incompatible API MINOR version with plugin. plugin MINOR API version: %s, Ours: %s. Please upgrade Packer.","messagePattern":"Incompatible API MINOR version with plugin\\. plugin MINOR API version: (.+?), Ours: (.+?)\\. Please upgrade Packer\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packer/plugin_client.go","lineNumber":349,"sourceCode":"\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)\n\t}\n\n\treturn c.address, err\n}\n","sourceCodeStart":331,"sourceCodeEnd":367,"githubUrl":"https://github.com/hashicorp/packer/blob/eb36e3c3e48a036f3e8cc94087636ee72e1303c9/packer/plugin_client.go#L331-L367","documentation":"If the handshake's major versions match, Packer compares minor API versions. The plugin must not be newer than the host, so a plugin minor version greater than Packer's APIVersionMinor aborts startup, telling you to upgrade Packer.","triggerScenarios":"Client.Start() in packer/plugin_client.go sees pluginMinorAPIVersion > pluginsdk.APIVersionMinor — a plugin compiled with a newer (minor-bumped) packer-plugin-sdk than this Packer binary embeds.","commonSituations":"Installing the latest plugin release right after an SDK bump while still running an older Packer; pinning plugins=latest in required_plugins while Packer is outdated; CI images with a frozen old Packer but fresh plugin downloads.","solutions":["Upgrade Packer to the latest release so its APIVersionMinor >= the plugin's.","Pin the plugin to an older version compatible with your Packer (e.g. `version = \"~> 1.0.8\"` in required_plugins).","In CI, upgrade the Packer install step alongside plugin installation."],"exampleFix":"// before: required_plugins { install { source = \"github.com/hashicorp/amazon\" version = \">= 1.2.0\" } }\n// with an old Packer -> minor version error\n// after: pin compatible plugin or upgrade Packer\npacker { required_plugins { amazon = { source = \"github.com/hashicorp/amazon\", version = \"~> 1.2\" } } }\n$ packer plugins install github.com/hashicorp/amazon","handlingStrategy":"validation","validationCode":"out, _ := exec.Command(pluginPath, \"packer-plugin\").Output()\nparts := strings.Split(strings.TrimSpace(string(out)), \"|\")\nif len(parts) >= 2 && parts[1] > pluginsdk.APIVersionMinor { /* upgrade Packer or pin older plugin */ }","typeGuard":null,"tryCatchPattern":"if _, err := client.Start(); err != nil {\n  if strings.Contains(err.Error(), \"Incompatible API MINOR version\") {\n    // upgrade Packer (recommended) or pin an older plugin version\n  }\n}","preventionTips":["Upgrade Packer before installing newly released plugins.","Avoid version constraints like \">=\" that always take the latest plugin.","Keep CI Packer installs in sync with plugin installation."],"tags":["plugin-protocol","version-compatibility","upgrade"],"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"}