{"record":{"id":"62053bba34cfc5bb","repo":"hashicorp/nomad","slug":"failed-to-create-container-configuration-for-image","errorCode":null,"errorMessage":"Failed to create container configuration for image %q (%q): %v","messagePattern":"Failed to create container configuration for image %q \\(%q\\): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/driver.go","lineNumber":390,"sourceCode":"\t}\n\n\t// validate the image user (windows only)\n\tif err := validateImageUser(user, cfg.User, &driverConfig, d.config); err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tif runtime.GOOS == \"windows\" {\n\t\terr = d.convertAllocPathsForWindowsLCOW(cfg, driverConfig.Image)\n\t\tif err != nil {\n\t\t\treturn nil, nil, err\n\t\t}\n\t}\n\n\tcontainerCfg, err := d.createContainerConfig(cfg, &driverConfig, driverConfig.Image)\n\tif err != nil {\n\t\td.logger.Error(\"failed to create container configuration\", \"image_name\", driverConfig.Image,\n\t\t\t\"image_id\", id, \"error\", err)\n\t\treturn nil, nil, fmt.Errorf(\"Failed to create container configuration for image %q (%q): %v\", driverConfig.Image, id, err)\n\t}\n\n\tstartAttempts := 0\nCREATE:\n\tcontainer, err := d.createContainer(dockerClient, containerCfg, driverConfig.Image)\n\tif err != nil {\n\t\td.logger.Error(\"failed to create container\", \"error\", err)\n\t\tif container != nil {\n\t\t\t_, removeErr := dockerClient.ContainerRemove(d.ctx, container.Container.ID, mclient.ContainerRemoveOptions{Force: true})\n\t\t\tif removeErr != nil {\n\t\t\t\treturn nil, nil, fmt.Errorf(\"failed to remove container %s: %v\", container.Container.ID, removeErr)\n\t\t\t}\n\t\t}\n\t\treturn nil, nil, nstructs.WrapRecoverable(fmt.Sprintf(\"failed to create container: %v\", err), err)\n\t}\n\n\td.logger.Info(\"created container\", \"container_id\", container.Container.ID)\n","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/driver.go#L372-L408","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nport_map { http = 8080 } // task has no port labeled http\n// after\nport_map { http = \"http\" } // matches an existing dynamic/static port label named http","handlingStrategy":"validation","validationCode":"// Pre-validate task driver config before StartTask:\nfor label := range cfg.PortMap {\n    if _, ok := task.Resources.Ports[label]; !ok {\n        return fmt.Errorf(\"port_map references missing port label %q\", label)\n    }\n}\nfor _, m := range cfg.Mounts {\n    if _, err := os.Stat(m.Source); err != nil { return fmt.Errorf(\"mount source missing: %w\", err) }\n}\nif err := validateCaps(cfg.CapAdd); err != nil { return err }","typeGuard":"func isContainerConfigErr(err error) bool {\n    return strings.Contains(err.Error(), \"Failed to create container configuration\")\n}","tryCatchPattern":"handle, err := d.StartTask(ctx, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"Failed to create container configuration\") {\n        // fix task config fields (ports, mounts, caps, security-opt) and resubmit\n    }\n    return err\n}","preventionTips":["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"],"tags":["docker","task-configuration","validation"],"backgroundTag":"container-config-invalid","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}