{"record":{"id":"fa24a2fe84be4189","repo":"docker/cli","slug":"invalid-image-reference-for-service-s-w","errorCode":null,"errorMessage":"invalid image reference for service %s: %w","messagePattern":"invalid image reference for service (.+?): %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/stack/loader.go","lineNumber":60,"sourceCode":"\tunsupportedProperties := loader.GetUnsupportedProperties(dicts...)\n\tif len(unsupportedProperties) > 0 {\n\t\t_, _ = fmt.Fprintf(streams.Err(), \"Ignoring unsupported options: %s\\n\\n\",\n\t\t\tstrings.Join(unsupportedProperties, \", \"))\n\t}\n\n\tdeprecatedProperties := loader.GetDeprecatedProperties(dicts...)\n\tif len(deprecatedProperties) > 0 {\n\t\t_, _ = fmt.Fprintf(streams.Err(), \"Ignoring deprecated options:\\n\\n%s\\n\\n\",\n\t\t\tpropertyWarnings(deprecatedProperties))\n\t}\n\n\t// Validate if each service has a valid image-reference.\n\tfor _, svc := range config.Services {\n\t\tif svc.Image == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"invalid image reference for service %s: no image specified\", svc.Name)\n\t\t}\n\t\tif _, err := reference.ParseAnyReference(svc.Image); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"invalid image reference for service %s: %w\", svc.Name, err)\n\t\t}\n\t}\n\n\treturn config, nil\n}\n\nfunc getDictsFrom(configFiles []composetypes.ConfigFile) []map[string]any {\n\tdicts := make([]map[string]any, 0, len(configFiles))\n\tfor _, configFile := range configFiles {\n\t\tdicts = append(dicts, configFile.Config)\n\t}\n\n\treturn dicts\n}\n\nfunc propertyWarnings(properties map[string]string) string {\n\tmsgs := make([]string, 0, len(properties))\n\tfor name, description := range properties {","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/stack/loader.go#L42-L78","documentation":"Raised by loadComposeFile when a service has an image value that fails reference.ParseAnyReference, meaning the image string is not a valid OCI/Docker reference (illegal characters, malformed digest/tag, uppercase in domain handling, etc.). The wrapped %w carries the reference parser error.","triggerScenarios":"A compose service with `image:` set to a malformed string (e.g. contains spaces, illegal characters, malformed digest, or empty repo). ParseAnyReference at loader.go:59 rejects it and the error wraps the parser detail.","commonSituations":"Typos in image tags; embedding a digest incorrectly (`image: foo@sha256:not-hex`); trailing whitespace from templating; uppercase letters where lowercase is required; using a bare digest without repo prefix.","solutions":["Read the wrapped parser error for the precise malformation.","Correct the image string to the form [registry/]repo[:tag][@digest].","Strip stray whitespace/quotes introduced by templating or env vars.","Validate the reference with `docker pull <image>` before deploying."],"exampleFix":"# before\nservices:\n  web:\n    image: myrepo/web: latest   # stray space\n# after\nservices:\n  web:\n    image: myrepo/web:latest","handlingStrategy":"validation","validationCode":"// Validate each service image reference before deploy\nfor _, svc := range config.Services {\n    if _, err := reference.ParseAnyReference(svc.Image); err != nil {\n        return fmt.Errorf(\"service %s invalid image %q: %w\", svc.Name, svc.Image, err)\n    }\n}","typeGuard":"// Narrow: type that guarantees a parsed reference\ntype ValidImage struct{ ref reference.AnyReference }\n\nfunc NewValidImage(s string) (ValidImage, error) {\n    r, err := reference.ParseAnyReference(s)\n    if err != nil {\n        return ValidImage{}, err\n    }\n    return ValidImage{ref: r}, nil\n}","tryCatchPattern":null,"preventionTips":["Strip whitespace and stray quotes from templated image values.","Validate references with reference.ParseAnyReference in tests.","Cross-check by `docker pull <image>` before deploy."],"tags":["docker","stack","compose","image","reference","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}