hashicorp/nomad · error
Failed to create container configuration for image
Error message
Failed to create container configuration for image %q (%q): %v
What it means
StartTask failed while building the Docker container configuration (d.createContainerConfig) for the already-pulled image. This is thrown when task config fields cannot be translated into a docker container.Config/HostConfig (e.g. invalid port labels, bad mounts, unsupported options), not when the image itself is bad. The message includes the image name and image id for correlation.
Solutions
- Read the wrapped %v cause and the 'failed to create container configuration' log line to see which config field is rejected
- Fix the offending task driver config field (port map labels, mounts, caps, security opts)
- Verify referenced port labels exist in the task's network stanza and files/dirs referenced by mounts exist
- Test the same options with a raw `docker run` to confirm the daemon accepts them
Example fix
// before
port_map { http = 8080 } // task has no port labeled http
// after
port_map { http = "http" } // matches an existing dynamic/static port label named http Defensive patterns
Strategy: validation
Validate before calling
// Pre-validate task driver config before StartTask:
for label := range cfg.PortMap {
if _, ok := task.Resources.Ports[label]; !ok {
return fmt.Errorf("port_map references missing port label %q", label)
}
}
for _, m := range cfg.Mounts {
if _, err := os.Stat(m.Source); err != nil { return fmt.Errorf("mount source missing: %w", err) }
}
if err := validateCaps(cfg.CapAdd); err != nil { return err } Type guard
func isContainerConfigErr(err error) bool {
return strings.Contains(err.Error(), "Failed to create container configuration")
} Try / catch
handle, err := d.StartTask(ctx, cfg)
if err != nil {
if strings.Contains(err.Error(), "Failed to create container configuration") {
// fix task config fields (ports, mounts, caps, security-opt) and resubmit
}
return err
} Prevention
- Cross-check every port_map key against declared task network port labels
- Stat-check all volume/mount source paths on the host before task submission
- Test equivalent options with `docker run` before encoding them in task config
- Avoid deprecated driver options; pin daemon + driver versions and read release notes
When it happens
Trigger: StartTask calls d.createContainerConfig(cfg, &driverConfig, driverConfig.Image) and it errors: invalid task driver config such as malformed port_map/port labels, invalid mounts/volumes, bad security-opt or sysctl values, unsupported caps, invalid logging config, or DNS/hostname options the daemon config rejects at config-build time.
Common situations: Typo'd or nonexistent port label referenced in port_map; volume/mount source paths that don't exist or aren't allowed; invalid security_opt or cap_add values; devices paths missing on host; incompatible options for Windows/LCOW tasks; deprecated docker driver options used with a newer daemon.
Related errors
- cannot apply allowed_modes configuration
- cannot apply allowed_modes configuration
- cannot apply allowed_modes configuration
- cannot apply allowed_modes configuration
- cmd is required, but was empty
AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04).
Data as JSON: /api/errors/62053bba34cfc5bb.
Report an issue: GitHub.
Appendix: source
Thrown at drivers/docker/driver.go:390
}
// validate the image user (windows only)
if err := validateImageUser(user, cfg.User, &driverConfig, d.config); err != nil {
return nil, nil, err
}
if runtime.GOOS == "windows" {
err = d.convertAllocPathsForWindowsLCOW(cfg, driverConfig.Image)
if err != nil {
return nil, nil, err
}
}
containerCfg, err := d.createContainerConfig(cfg, &driverConfig, driverConfig.Image)
if err != nil {
d.logger.Error("failed to create container configuration", "image_name", driverConfig.Image,
"image_id", id, "error", err)
return nil, nil, fmt.Errorf("Failed to create container configuration for image %q (%q): %v", driverConfig.Image, id, err)
}
startAttempts := 0
CREATE:
container, err := d.createContainer(dockerClient, containerCfg, driverConfig.Image)
if err != nil {
d.logger.Error("failed to create container", "error", err)
if container != nil {
_, removeErr := dockerClient.ContainerRemove(d.ctx, container.Container.ID, mclient.ContainerRemoveOptions{Force: true})
if removeErr != nil {
return nil, nil, fmt.Errorf("failed to remove container %s: %v", container.Container.ID, removeErr)
}
}
return nil, nil, nstructs.WrapRecoverable(fmt.Sprintf("failed to create container: %v", err), err)
}
d.logger.Info("created container", "container_id", container.Container.ID)
View on GitHub (pinned to 482b49bf1a)