hashicorp/packer · error

error initializing builder '%s': %s

Error message

error initializing builder '%s': %s

What it means

The builder plugin type was found and Packer launched it via Builders.Start, but the plugin process failed to start or errored during startup/handshake. Packer wraps the underlying error with the builder type.

Source

Thrown at packer/core.go:478

			"The builder %s is unknown by Packer, and is likely part of a plugin that is not installed.\n"+
				"You may find the needed plugin along with installation instructions documented on the Packer integrations page.\n\n"+
				"https://developer.hashicorp.com/packer/integrations?filter=%s",
			configBuilder.Type,
			strings.Split(configBuilder.Type, "-")[0],
		)

		if sugg := didyoumean.NameSuggestion(configBuilder.Type, c.components.PluginConfig.Builders.List()); sugg != "" {
			err = fmt.Errorf("Did you mean to use %q?", sugg)
		}

		return nil, err
	}

	// the Start command launches the builder plugin of the given type without
	// calling Prepare() or passing any build-specific details.
	builder, err := c.components.PluginConfig.Builders.Start(configBuilder.Type)
	if err != nil {
		return nil, fmt.Errorf(
			"error initializing builder '%s': %s",
			configBuilder.Type, err)
	}
	if builder == nil {
		return nil, fmt.Errorf(
			"builder type not found: %s", configBuilder.Type)
	}

	// rawName is the uninterpolated name that we use for various lookups
	rawName := configBuilder.Name

	// Setup the provisioners for this build
	provisioners := make([]CoreBuildProvisioner, 0, len(c.Template.Provisioners))
	for _, rawP := range c.Template.Provisioners {
		// If we're skipping this, then ignore it
		if rawP.OnlyExcept.Skip(rawName) {
			continue
		}

View on GitHub (pinned to eb36e3c3e4)

Solutions

1. Inspect the wrapped inner error; reinstall the plugin (`packer plugins install <source>`) to replace a corrupt binary.
2. Upgrade the plugin to a version compatible with your Packer release.
3. Verify the binary runs standalone from the plugin directory.
4. Check disk space and file permissions in the plugin path.

Example fix

# before
$ packer build .
# error initializing builder 'amazon-ebs': ...
# after
$ packer init .
$ packer plugins install github.com/hashicorp/amazon
$ packer build .

// Smoke-test plugin executability before the build:
out, err := exec.Command("packer", "plugins", "installed").Output()

if _, err := core.Build(n); err != nil {
    if strings.Contains(err.Error(), "error initializing builder") {
        // reinstall the plugin, then retry the build once
        exec.Command("packer", "plugins", "install", pluginSource).Run()
        if _, retryErr := core.Build(n); retryErr != nil {
            return retryErr
        }
        return nil
    }
    return err
}

When it happens

Trigger: Core.Build: c.components.PluginConfig.Builders.Start(configBuilder.Type) returns a non-nil error — plugin binary missing/corrupt despite registry entry, exec failure, crash on startup, or incompatible plugin protocol version. Raised during `packer build`.

Common situations: Plugin built against an older SDK incompatible with the current Packer core; broken install left a stale binary; plugin panics at init; filesystem permissions preventing exec; disk full preventing plugin launch.

Related errors

• error initializing provisioner '%s': %s
• The builder %s is unknown by Packer, and is likely part of a
• builder type not found: %s
• error initializing post-processor '%s': %s
• load keyless trusted root: %w

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