hashicorp/nomad · error

Failed to create container configuration for image %q (%q):

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.

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)

Solutions

1. Read the wrapped %v cause and the 'failed to create container configuration' log line to see which config field is rejected
2. Fix the offending task driver config field (port map labels, mounts, caps, security opts)
3. Verify referenced port labels exist in the task's network stanza and files/dirs referenced by mounts exist
4. 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

// 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 }

func isContainerConfigErr(err error) bool {
    return strings.Contains(err.Error(), "Failed to create container configuration")
}

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
}

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

• does not match registry specification
• invalid cgroup permission string: %q
• invalid source, must be "" for tmpfs
• invalid mount type, must be "bind", "volume", "tmpfs": %q
• cannot apply allowed_modes configuration, %q is not a valid

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/62053bba34cfc5bb. Report an issue: GitHub.