{"record":{"id":"6a3535ecb42b9ef5","repo":"dagger/dagger","slug":"invalid-image-ref-q","errorCode":null,"errorMessage":"invalid image ref %q","messagePattern":"invalid image ref %q","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdk/python/runtime/image.go","lineNumber":102,"sourceCode":"\t\treturn nil\n\t}\n\timg, err := NewImage(ref)\n\tif err != nil {\n\t\treturn err\n\t}\n\ti.named = img.named\n\treturn nil\n}\n\n// NewImage parses a string into a named reference transforming a familiar\n// name from Docker UI to a fully qualified reference.\nfunc NewImage(ref string) (Image, error) {\n\tnamed, err := reference.ParseNormalizedNamed(ref)\n\tif err != nil {\n\t\treturn Image{}, err\n\t}\n\tif named == nil {\n\t\treturn Image{}, fmt.Errorf(\"invalid image ref %q\", ref)\n\t}\n\treturn Image{named: named}, nil\n}\n\n// extractImages reads from the bundled Dockerfile to extract the default docker\n// image references.\nfunc extractImages() (map[string]Image, error) {\n\timages := make(map[string]Image)\n\tfor _, dockerfile := range []string{baseDockerfile, uvDockerfile} {\n\t\tlines := strings.Split(dockerfile, \"\\n\")\n\n\t\tfor _, line := range lines {\n\t\t\tif matches := fromLineRegex.FindStringSubmatch(strings.TrimSpace(line)); matches != nil {\n\t\t\t\tref := matches[1]\n\t\t\t\tname := matches[2]\n\n\t\t\t\timage, err := NewImage(ref)\n\t\t\t\tif err != nil {","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/dagger/dagger/blob/82ba2681dbe30d3547a1dc50ea495900ab5b6047/sdk/python/runtime/image.go#L84-L120","documentation":"NewImage() parses a Docker image reference with distribution/reference's ParseNormalizedNamed. Normally the parse error is returned directly; the 'invalid image ref %q' wrapper fires when parsing succeeds but yields a nil named reference, indicating a structurally unusable (empty) input that slipped through. Called by parseBaseImage, UnmarshalJSON, and extractImages.","triggerScenarios":"Passing an empty string or a string that parses to a nil named ref to NewImage — e.g. an unset environment variable or missing Dockerfile FROM line feeding parseBaseImage/extractImages, or an empty image field during JSON unmarshal.","commonSituations":"Missing BASE_IMAGE-style env override; bundled Dockerfile with an empty image placeholder; dagger.json or API payload carrying an empty/blank image string; typos in image names that fail normalization.","solutions":["Check the %q value in the message to find the offending config/env source and supply a valid image reference.","Ensure any image-setting env var or dagger.json field is non-empty (e.g. python:3.12-slim-bookworm).","Reinstall the dagger CLI if the embedded Dockerfile is damaged/empty.","Validate image refs before passing them to the runtime (see validationCode)."],"exampleFix":"// before\ncfg.BaseImage = os.Getenv(\"DAGGER_BASE_IMAGE\") // \"\"\n// after\ncfg.BaseImage = os.Getenv(\"DAGGER_BASE_IMAGE\")\nif cfg.BaseImage == \"\" { cfg.BaseImage = \"python:3.12-slim-bookworm\" }","handlingStrategy":"validation","validationCode":"// Go: validate an image ref before handing it to the runtime\nif strings.TrimSpace(ref) == \"\" {\n    return fmt.Errorf(\"image ref is empty; set DAGGER_BASE_IMAGE or a default\")\n}","typeGuard":null,"tryCatchPattern":"img, err := runtime.NewImage(ref)\nif err != nil {\n    if strings.Contains(err.Error(), \"invalid image ref\") {\n        return fmt.Errorf(\"image ref %q is invalid/empty; check env and config: %w\", ref, err)\n    }\n    return err\n}","preventionTips":["Provide fallback defaults for image-setting env vars","Never leave image fields blank in dagger.json or API payloads","Reinstall the CLI if embedded runtime Dockerfile assets appear damaged"],"tags":["go","python-sdk","image-ref","validation"],"backgroundTag":"invalid-image-reference","analyzedSha":"82ba2681dbe30d3547a1dc50ea495900ab5b6047","analyzedAt":"2026-09-05T07:21:37.930Z","contentChangedAt":"2026-09-05T07:21:37.930Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}