What causes "`max_retries` must be a valid integer: %s" in hashicorp/packer?

Set max_retries to a plain integer such as max_retries = 3

`max_retries` must be a valid integer: %s

Error message

`max_retries` must be a valid integer: %s

What it means

Template validation error in generateCoreBuildProvisionerWithProvisioner: the provisioner's `max_retries` value interpolated successfully but is not an integer string (strconv.Atoi failed), e.g. max_retries = "three" or "2.0".

Source

Thrown at packer/core.go:300

		provisioner = &PausedProvisioner{
			PauseBefore: rawP.PauseBefore,
			Provisioner: provisioner,
		}
	} else if rawP.Timeout != 0 {
		provisioner = &TimeoutProvisioner{
			Timeout:     rawP.Timeout,
			Provisioner: provisioner,
		}
	}
	maxRetries := 0
	if rawP.MaxRetries != "" {
		renderedMaxRetries, err := interpolate.Render(rawP.MaxRetries, c.Context())
		if err != nil {
			return cbp, fmt.Errorf("failed to interpolate `max_retries`: %s", err.Error())
		}
		maxRetries, err = strconv.Atoi(renderedMaxRetries)
		if err != nil {
			return cbp, fmt.Errorf("`max_retries` must be a valid integer: %s", err.Error())
		}
	}
	if maxRetries != 0 {
		provisioner = &RetriedProvisioner{
			MaxRetries:  maxRetries,
			Provisioner: provisioner,
		}
	}

	if rawP.Type == "hcp-sbom" {
		provisioner = &SBOMInternalProvisioner{
			Provisioner: provisioner,
		}
	}

	cbp = CoreBuildProvisioner{
		PType:       rawP.Type,
		Provisioner: provisioner,

View on GitHub (pinned to eb36e3c3e4)

Solutions

Set max_retries to a plain integer such as max_retries = 3
If interpolated, ensure the variable resolves to a numeric string without quotes/whitespace

Example fix

// before
"max_retries": "{{env `RETRIES`}}"   # RETRIES="3x"
// after
"max_retries": "{{env `RETRIES`}}"   # RETRIES=3

Defensive patterns

Strategy: validation

Validate before calling

// Caller-side numeric check mirroring strconv.Atoi:
n, err := strconv.Atoi(strings.TrimSpace(renderedMaxRetries))
if err != nil || n < 0 {
    return fmt.Errorf("max_retries %q must be a non-negative integer", renderedMaxRetries)
}

Prevention

Store max_retries values as plain integer strings without whitespace or units.
Use HCL2 variable validation (can(tonumber(var.x))) to enforce numeric input.
Avoid env-var indirection for numeric settings when possible.
Add CI validation step that renders the template and parses max_retries.

When it happens

Trigger: generateCoreBuildProvisionerWithProvisioner: renderedMaxRetries (result of interpolate.Render of rawP.MaxRetries) is not parseable by strconv.Atoi — e.g. 'three', '3.5', '' (an env var set to empty string), or text with whitespace/suffixes. Raised during Core.Build and also reachable via GenerateCoreBuildProvisionerFromHCLBody.

Common situations: Env/user variable interpolated into max_retries containing a non-integer value ('', 'yes', '3 retries'); user quoting the number with units; locale-formatted numbers; decimal values.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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