hashicorp/packer · error

Incompatible API MAJOR version with plugin. plugin MINOR API

Error message

Incompatible API MAJOR version with plugin. plugin MINOR API version: %s, Ours: %s

What it means

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.

Source

Thrown at packer/plugin_client.go:344

		line := strings.TrimSpace(string(lineBytes))
		parts := strings.SplitN(line, "|", 4)
		if len(parts) == 3 {
			// In protocol version 4 and before, the protocol only had a Major
			// version
			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)

View on GitHub (pinned to eb36e3c3e4)

Solutions

  1. Upgrade Packer to a release supporting the plugin's major API version (usually the fix when plugin major > ours).
  2. Downgrade or reinstall the plugin at a release matching your Packer's supported API major version.
  3. Rebuild the plugin against the packer-plugin-sdk version compatible with your Packer.

Example fix

// before: new plugin + old packer
// error: Incompatible API MAJOR version with plugin. plugin MINOR API version: 1, Ours: ...
// after
$ packer --version           # check current version
$ brew upgrade hashicorp/tap/packer   # or download latest release, then retry
Defensive patterns

Strategy: validation

Validate before calling

// check plugin handshake major version before starting
out, _ := exec.Command(pluginPath, "packer-plugin").Output()
parts := strings.Split(strings.TrimSpace(string(out)), "|")
if len(parts) >= 1 && parts[0] != pluginsdk.APIVersionMajor { /* upgrade/downgrade Packer or plugin */ }

Try / catch

if _, err := client.Start(); err != nil {
  if strings.Contains(err.Error(), "Incompatible API MAJOR version") {
    // upgrade Packer or pick a matching plugin release
  }
}

Prevention

When it happens

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

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

Related errors

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