Incompatible API MINOR version with plugin. plugin MINOR API

Error message

Incompatible API MINOR version with plugin. plugin MINOR API version: %s, Ours: %s. Please upgrade Packer.

What it means

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.

Source

Thrown at packer/plugin_client.go:349

			err = fmt.Errorf("The protocol of this plugin (protocol version 4 " +
				"and lower) was deprecated, please use a newer version of this plugin." +
				"Or use an older version of Packer (pre 1.7) with this plugin.")
			return nil, err
		}
		if len(parts) < 4 {
			err = fmt.Errorf("Unrecognized remote plugin message: %s", line)
			return nil, err
		}
		pluginMajorAPIVersion, pluginMinorAPIVersion, network, netAddr := parts[0], parts[1], parts[2], parts[3]

		// Test the API versions
		if pluginMajorAPIVersion != pluginsdk.APIVersionMajor {
			err = fmt.Errorf("Incompatible API MAJOR version with plugin. "+
				"plugin MINOR API version: %s, Ours: %s", pluginMajorAPIVersion, pluginsdk.APIVersionMajor)
			return nil, err
		}
		if pluginMinorAPIVersion > pluginsdk.APIVersionMinor {
			err = fmt.Errorf("Incompatible API MINOR version with plugin. "+
				"plugin MINOR API version: %s, Ours: %s. Please upgrade Packer.", pluginMinorAPIVersion, pluginsdk.APIVersionMinor)
			return nil, err
		}

		switch network {
		case "tcp":
			c.address, err = net.ResolveTCPAddr("tcp", netAddr)
		case "unix":
			c.address, err = net.ResolveUnixAddr("unix", netAddr)
		default:
			return nil, fmt.Errorf("Unknown address type: %s", network)
		}
		log.Printf("Received %s RPC address for %s: addr is %s", network, cmd.Path, c.address)
	}

	return c.address, err
}

View on GitHub (pinned to eb36e3c3e4)

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.

Example fix

// before: required_plugins { install { source = "github.com/hashicorp/amazon" version = ">= 1.2.0" } }
// with an old Packer -> minor version error
// after: pin compatible plugin or upgrade Packer
packer { required_plugins { amazon = { source = "github.com/hashicorp/amazon", version = "~> 1.2" } } }
$ packer plugins install github.com/hashicorp/amazon

Defensive patterns

Strategy: validation

Validate before calling

out, _ := exec.Command(pluginPath, "packer-plugin").Output()
parts := strings.Split(strings.TrimSpace(string(out)), "|")
if len(parts) >= 2 && parts[1] > pluginsdk.APIVersionMinor { /* upgrade Packer or pin older plugin */ }

Try / catch

if _, err := client.Start(); err != nil {
  if strings.Contains(err.Error(), "Incompatible API MINOR version") {
    // upgrade Packer (recommended) or pin an older plugin version
  }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hashicorp/packer@eb36e3c3e4 (2026-09-05). Data as JSON: /api/errors/0c2b42c87b3bf6ea. Report an issue: GitHub.