What causes "Unknown builder %s" in hashicorp/packer?

Fix the source/builder type name in the template (check `packer plugins list`).

Unknown builder %s

Error message

Unknown builder %s

What it means

MapOfBuilder.Start returns this error when the requested builder name is not a key in the registry map. It indicates Packer could not resolve the builder referenced by a source/build block — the builder plugin is unknown to the running Packer binary.

Source

Thrown at packer/maps.go:80

	}
	return res
}

type MapOfBuilder map[string]func() (packersdk.Builder, error)

func (mob MapOfBuilder) Has(builder string) bool {
	_, res := mob[builder]
	return res
}

func (mob MapOfBuilder) Set(builder string, starter func() (packersdk.Builder, error)) {
	mob[builder] = starter
}

func (mob MapOfBuilder) Start(builder string) (packersdk.Builder, error) {
	d, found := mob[builder]
	if !found {
		return nil, fmt.Errorf("Unknown builder %s", builder)
	}
	return d()
}

func (mob MapOfBuilder) List() []string {
	res := []string{}
	for k := range mob {
		res = append(res, k)
	}
	return res
}

type MapOfDatasource map[string]func() (packersdk.Datasource, error)

func (mod MapOfDatasource) Has(dataSource string) bool {
	_, res := mod[dataSource]
	return res
}

View on GitHub (pinned to eb36e3c3e4)

Solutions

Fix the source/builder type name in the template (check `packer plugins list`).
Run `packer init .` to install plugins declared in required_plugins.
Ensure the plugin binary follows the github.com/<org>/<name> PACKER_PLUGIN_PATH naming layout.
In embedded Go usage, register the builder with Set() before Start().

Example fix

// before (typo)
source "amazon-ebs2" { ... }

// after
source "amazon-ebs" { ... }

Defensive patterns

Strategy: validation

Validate before calling

if !builders.Has(name) {
    return fmt.Errorf("builder %q not found; run `packer init` (known: %v)", name, builders.List())
}
b, err := builders.Start(name)

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "Unknown builder") { /* install the plugin, then retry */ }
}

Prevention

Always declare builder plugins in required_plugins with version constraints.
Run `packer validate` before `packer build`.
Verify plugin binaries exist in PACKER_PLUGIN_PATH after CI image updates.

When it happens

Trigger: Calling Start(builder) with an unregistered name: source block type misspelled (e.g. "amazon-ebs2"), a builder plugin not declared in required_plugins/installed, or a name registered only via a plugin binary that wasn't discovered.

Common situations: Misspelled source type in HCL2 template; forgot `packer init`; third-party builder plugin binary missing or misnamed; upgrading Packer where a legacy builtin (e.g. from JSON templates) no longer exists.

Related errors

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