error retrieving image iteration from HCP Packer registry: %

Error message

error retrieving image iteration from HCP Packer registry: %s

What it means

Returned by the (deprecated) hcp-packer-image datasource's Execute() when cli.GetIteration() fails to fetch the iteration identified by iteration_id from the HCP Packer Registry. The underlying client error is wrapped into the message, so %s carries the actual HTTP/auth cause. The datasource returns a null cty value and the build cannot continue.

Source

Thrown at datasource/hcp-packer-image/data.go:160

func (d *Datasource) Execute() (cty.Value, error) {
	log.Printf("[WARN] Deprecation: `hcp-packer-image` datasource has been deprecated. " +
		"Please use `hcp-packer-artifact` datasource instead.")
	ctx := context.TODO()

	cli, err := hcpapi.NewDeprecatedClient()
	if err != nil {
		return cty.NullVal(cty.EmptyObject), err
	}

	var iteration *hcpPackerDeprecatedModels.HashicorpCloudPackerIteration
	var channelID string
	if d.config.IterationID != "" {
		log.Printf("[INFO] Reading info from HCP Packer registry (%s) [project_id=%s, organization_id=%s, iteration_id=%s]",
			d.config.Bucket, cli.ProjectID, cli.OrganizationID, d.config.IterationID)

		iter, err := cli.GetIteration(ctx, d.config.Bucket, hcpapi.GetIteration_byID(d.config.IterationID))
		if err != nil {
			return cty.NullVal(cty.EmptyObject), fmt.Errorf(
				"error retrieving image iteration from HCP Packer registry: %s",
				err)
		}
		iteration = iter
	} else {
		log.Printf("[INFO] Reading info from HCP Packer registry (%s) [project_id=%s, organization_id=%s, channel=%s]",
			d.config.Bucket, cli.ProjectID, cli.OrganizationID, d.config.Channel)

		channel, err := cli.GetChannel(ctx, d.config.Bucket, d.config.Channel)
		if err != nil {
			return cty.NullVal(cty.EmptyObject), fmt.Errorf("error retrieving "+
				"channel from HCP Packer registry: %s", err.Error())
		}

		if channel.Iteration == nil {
			return cty.NullVal(cty.EmptyObject), fmt.Errorf("there is no iteration associated with the channel %s",
				d.config.Channel)
		}

View on GitHub (pinned to eb36e3c3e4)

Solutions

Verify the iteration_id (ULID) belongs to the bucket_name and HCP project bound to your credentials.
Confirm HCP_CLIENT_ID/HCP_CLIENT_SECRET are set and valid.
Check network/proxy access to the HCP API and retry transient failures.
Migrate to the hcp-packer-artifact datasource (this one logs a deprecation warning and uses deprecated models/endpoints).

Example fix

// before
data "hcp-packer-image" "example" {
  bucket_name = "my-bucket"
  iteration_id = "01HX...WRONG" # ID from another project
  region = "us-east-1"
  cloud_provider = "aws"
}
// after
data "hcp-packer-image" "example" {
  bucket_name = "my-bucket"
  iteration_id = "01HXXXXXXXXXXXXXXXXXXXXXXX" # correct ULID from this bucket
  region = "us-east-1"
  cloud_provider = "aws"
}

Defensive patterns

Strategy: try-catch

Validate before calling

if ! validULID(iterationID) {
    return fmt.Errorf("iteration_id %q is not a valid ULID", iterationID)
}
if os.Getenv("HCP_CLIENT_ID") == "" || os.Getenv("HCP_CLIENT_SECRET") == "" {
    return fmt.Errorf("HCP credentials missing")
}

Type guard

func validULID(s string) bool {
    if len(s) != 26 { return false }
    for _, r := range s {
        if !((r >= '0' && r <= '9') || (r >= 'A' && r <= 'Z' && r != 'I' && r != 'O')) { return false }
    }
    return true
}

Try / catch

try {
  packer build template.pkr.hcl
} catch (err) {
  if (String(err).includes("error retrieving image iteration from HCP Packer registry")) {
    console.error("Iteration lookup failed — verify iteration_id, bucket, project, and HCP credentials");
  }
  throw err;
}

Prevention

Copy iteration_id without truncation or whitespace from the HCP UI or publishing output.
Prefer the channel selector for stable lookups instead of raw iteration IDs.
Migrate to hcp-packer-artifact — this datasource and its endpoints are deprecated.

When it happens

Trigger: iteration_id is set (no channel) and GetIteration(ctx, bucket, GetIteration_byID(iteration_id)) errors: malformed ID, ID from another bucket/project, invalid HCP credentials, or the deprecated registry endpoint fails (404/401/5xx, network).

Common situations: Copying an iteration_id from a different registry/project; truncated ID or stray whitespace; missing HCP_CLIENT_ID/HCP_CLIENT_SECRET in CI; this legacy datasource hitting deprecated API endpoints newer projects no longer support.

Related errors

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