🚨 Packer Error: 'Error: Failed to prepare build: "amazon-ebs.ubuntu"' — Cause, Fix, and Troubleshooting Guide

Overview

Packer raises this during the prepare phase — before it ever talks to a cloud API — when it cannot fully resolve a build’s source. The build block references sources = ["source.amazon-ebs.ubuntu"], but Packer could not construct that source: either the amazon plugin is not installed, the builder type is misspelled, the named source block does not exist, or a variable/local the source depends on failed to evaluate.

Error: Failed to prepare build: "amazon-ebs.ubuntu"

  on build.pkr.hcl line 2:
  (source code not available)

1 error(s) occurred:

* Bad source 'amazon-ebs.ubuntu': No available Amazon plugin installed, or
  the builder type is unknown.

Because it fails at prepare time, nothing is provisioned and no instance is launched — which is good news: this is a template/configuration problem you can fix locally with packer init and packer validate.

Symptoms

• packer build or packer validate aborts immediately with Failed to prepare build.
• The message names a specific build, e.g. "amazon-ebs.ubuntu".
• A secondary line mentions “No available Amazon plugin installed” or “builder type is unknown”.
• packer init was never run, or the required_plugins block is missing.
• The source referenced in the build block does not match any source block label.

Common Root Causes

1. The Amazon plugin is not installed

Since Packer 1.7 the AWS builders live in an external plugin that must be declared and installed. Without it, amazon-ebs is an unknown builder.

packer {
  required_plugins {
    amazon = {
      source  = "github.com/hashicorp/amazon"
      version = ">= 1.2.0"
    }
  }
}

If this block is missing, or packer init was never run, prepare fails.

2. Builder type misspelled

amazon-esb, amazon_ebs, or aws-ebs are all invalid. The type must be exactly amazon-ebs.

source "amazon-ebs" "ubuntu" { ... }   # correct

3. The build block references a source that does not exist

The label in sources = [...] must match source "<type>" "<name>".

build {
  sources = ["source.amazon-ebs.ubuntu"]   # must match the source block label
}

A typo like source.amazon-ebs.ubunto produces this exact error.

4. A variable or local the source depends on failed to evaluate

If region = var.region and var.region has no default and no value supplied, the source cannot be prepared.

variable "region" {
  type = string   # no default → must be provided at runtime
}

5. Plugin installed for the wrong architecture or Packer version

An amd64 plugin binary on an arm64 runner, or a plugin built for an incompatible Packer API version, leaves the builder effectively unavailable.

How to Diagnose

Confirm the plugin is installed

packer plugins installed
packer init .

packer init reads required_plugins and downloads missing plugins. Run it in the template directory.

Validate the template

packer validate .

Validation reproduces the prepare phase without launching anything and pinpoints the offending build.

Turn on debug logging

PACKER_LOG=1 packer build . 2>&1 | head -50

The log shows which plugins loaded and which source failed to initialize.

Check source-to-build label matching

grep -nE 'source "|sources' *.pkr.hcl

Verify every entry in sources = [...] corresponds to a real source "<type>" "<name>" block.

Fixes

Install plugins with packer init

cd path/to/template
packer init .
packer plugins installed   # confirm github.com/hashicorp/amazon appears

Correct the builder type and source reference

source "amazon-ebs" "ubuntu" {
  region        = var.region
  instance_type = "t3.micro"
  source_ami    = "ami-0abcd1234example"
  ssh_username  = "ubuntu"
  ami_name      = "app-{{timestamp}}"
}

build {
  sources = ["source.amazon-ebs.ubuntu"]
}

Supply required variables

packer build -var 'region=us-east-1' .
# or export it
export PKR_VAR_region=us-east-1
packer build .

Pin and reinstall the correct plugin build

packer plugins remove github.com/hashicorp/amazon
packer init -upgrade .

What to Watch Out For

• Always run packer init in CI before packer build; the plugin cache is per-machine.
• Keep a required_plugins block with a version constraint so runners install a consistent plugin.
• Run packer validate as a pre-commit or pipeline gate — it catches every prepare-time error for free.
• Give variables sensible defaults where safe, and fail loudly (no default) only for values that must be explicit like region or account IDs.
• Match the plugin architecture to your build runner (arm64 vs amd64).

Related Guides

• Packer amazon-ebs Build Errored
• Packer Timeout Waiting for SSH
• IaC Testing Strategies That Actually Work