{"record":{"id":"18a111c0c58daa27","repo":"docker/cli","slug":"invalid-named-reference-bytes-s-w","errorCode":null,"errorMessage":"invalid named reference bytes: %s: %w","messagePattern":"invalid named reference bytes: (.+?): %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/manifest/types/types.go","lineNumber":144,"sourceCode":"\treturn ImageManifest{\n\t\tRef:         &SerializableNamed{Named: ref},\n\t\tDescriptor:  desc,\n\t\tRaw:         raw,\n\t\tOCIManifest: manifest,\n\t}\n}\n\n// SerializableNamed is a reference.Named that can be serialized and deserialized\n// from JSON\ntype SerializableNamed struct {\n\treference.Named\n}\n\n// UnmarshalJSON loads the Named reference from JSON bytes\nfunc (s *SerializableNamed) UnmarshalJSON(b []byte) error {\n\tvar raw string\n\tif err := json.Unmarshal(b, &raw); err != nil {\n\t\treturn fmt.Errorf(\"invalid named reference bytes: %s: %w\", b, err)\n\t}\n\tvar err error\n\ts.Named, err = reference.ParseNamed(raw)\n\treturn err\n}\n\n// MarshalJSON returns the JSON bytes representation\nfunc (s *SerializableNamed) MarshalJSON() ([]byte, error) {\n\treturn json.Marshal(s.String())\n}\n","sourceCodeStart":126,"sourceCodeEnd":155,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/manifest/types/types.go#L126-L155","documentation":"Returned by SerializableNamed.UnmarshalJSON (types.go:144) when the JSON bytes cannot be unmarshaled into a plain string. SerializableNamed wraps a reference.Named and expects its JSON representation to be a quoted string (the image reference), so any non-string JSON (object, number, array, malformed bytes) fails json.Unmarshal and is wrapped here. The raw bytes are printed for diagnosis.","triggerScenarios":"Deserializing an ImageManifest from JSON whose \"Ref\" field is not a JSON string — e.g. it is a nested object, null, a bare number, or the file is truncated/corrupted. Also triggered by a version mismatch where an older/newer format serialized Ref differently than a plain string.","commonSituations":"Hand-editing a cached manifest file and putting an object where a string is expected, a corrupt ~/.docker/manifests entry, or a tool that emits ImageManifest JSON with a non-string Ref representation.","solutions":["Validate the JSON before unmarshaling: ensure the Ref field is a JSON string.","Delete the malformed cached manifest and re-fetch it from the registry.","If you control serialization, always emit Ref as the string form of the reference (MarshalJSON does json.Marshal(s.String())).","Use json.Decoder with DisallowUnknownFields during development to catch schema drift early."],"exampleFix":"// before: unmarshaling trust-unchecked bytes\njson.Unmarshal(data, &img)\n\n// after: validate Ref is a string first\nvar probe map[string]json.RawMessage\n_ = json.Unmarshal(data, &probe)\nif v, ok := probe[\"Ref\"]; ok && len(v) > 0 && v[0] != '\"' {\n    return fmt.Errorf(\"Ref must be a JSON string, got %s\", v)\n}","handlingStrategy":"validation","validationCode":"// Validate the Ref field is a JSON string before unmarshaling into ImageManifest\nvar probe map[string]json.RawMessage\nif err := json.Unmarshal(data, &probe); err != nil {\n    return err\n}\nif v, ok := probe[\"Ref\"]; ok && (len(v) == 0 || v[0] != '\"') {\n    return fmt.Errorf(\"Ref must be a JSON string, got %s\", string(v))\n}","typeGuard":null,"tryCatchPattern":"// Catch the unmarshal error and purge corrupt cache\nif err := json.Unmarshal(data, &im); err != nil {\n    if strings.Contains(err.Error(), \"invalid named reference bytes\") {\n        _ = os.Remove(filename) // drop corrupt manifest cache\n    }\n    return err\n}","preventionTips":["Treat ~/.docker/manifests as opaque; don't edit by hand.","When serializing SerializableNamed, rely on MarshalJSON (emits a string).","Add schema validation in CI for any tool that writes these files."],"tags":["json","manifest","serialization","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}