hashicorp/packer · error

Failed to parse API Version from constraints

Error message

Failed to parse API Version from constraints: %s

What it means

CheckProtocolVersion() builds the LOCAL protocol version from binOpts.APIVersionMajor/Minor via NewAPIVersion(); if that construction fails (which can only happen if the constraint fields form an invalid version string), it returns this wrapped error. The remote side is parsed separately afterwards.

Solutions

1. Leave APIVersionMajor/APIVersionMinor at their defaults (the pluginsdk constants) unless you truly need to override.
2. If overriding, pass valid numeric major/minor values (e.g. 5 and 0).
3. Call installOpts.WithDefaultBinaryInstallationOptions() or similar SDK helpers to fill sane defaults before use.

Example fix

// before
binOpts := plugingetter.BinaryInstallationOptions{APIVersionMajor: "", APIVersionMinor: ""}
// after
binOpts.APIVersionMajor, binOpts.APIVersionMinor = pluginsdk.APIVersionMajor, pluginsdk.APIVersionMinor

if binOpts.APIVersionMajor == "" || binOpts.APIVersionMinor == "" {
	binOpts.APIVersionMajor, binOpts.APIVersionMinor = pluginsdk.APIVersionMajor, pluginsdk.APIVersionMinor
}

if err := binOpts.CheckProtocolVersion(entry.ProtVersion); err != nil {
	if strings.Contains(err.Error(), "Failed to parse API Version from constraints") {
		// reset binOpts to SDK defaults and retry
	}
}

When it happens

Trigger: Calling CheckProtocolVersion with BinaryInstallationOptions whose APIVersionMajor/APIVersionMinor (different from pluginsdk constants) produce a string like "x" or "x5." that NewAPIVersion cannot parse.

Common situations: Programmatic callers (custom installers/tests) populate APIVersionMajor/Minor with empty strings or non-numeric values instead of numbers like 5 and 0.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Invalid remote protocol
• unsupported remote protocol MAJOR version
• unsupported remote protocol MINOR version
• could not parse release
• decode attestation envelope

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

Appendix: source

Thrown at packer/plugin-getter/plugins.go:525

	return ver, nil
}

var localAPIVersion APIVersion

func (binOpts *BinaryInstallationOptions) CheckProtocolVersion(remoteProt string) error {
	// no protocol version check
	if binOpts.APIVersionMajor == "" && binOpts.APIVersionMinor == "" {
		return nil
	}

	localVersion := localAPIVersion
	if binOpts.APIVersionMajor != pluginsdk.APIVersionMajor ||
		binOpts.APIVersionMinor != pluginsdk.APIVersionMinor {
		var err error

		localVersion, err = NewAPIVersion(fmt.Sprintf("x%s.%s", binOpts.APIVersionMajor, binOpts.APIVersionMinor))
		if err != nil {
			return fmt.Errorf("Failed to parse API Version from constraints: %s", err)
		}
	}

	remoteVersion, err := NewAPIVersion(remoteProt)
	if err != nil {
		return err
	}

	if localVersion.Major != remoteVersion.Major {
		return fmt.Errorf("unsupported remote protocol MAJOR version %d. The current MAJOR protocol version is %d."+
			" This version of Packer can only communicate with plugins using that version", remoteVersion.Major, localVersion.Major)
	}

	if remoteVersion.Minor > localVersion.Minor {
		return fmt.Errorf("unsupported remote protocol MINOR version %d. The supported MINOR protocol versions are version %d and below. "+
			"Please upgrade Packer or use an older version of the plugin if possible", remoteVersion.Minor, localVersion.Minor)
	}

View on GitHub (pinned to eb36e3c3e4)