{"record":{"id":"c3d3f5eada104874","repo":"hashicorp/nomad","slug":"failed-to-encode-snapshot-metadata-v","errorCode":null,"errorMessage":"failed to encode snapshot metadata: %v","messagePattern":"failed to encode snapshot metadata: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/snapshot/archive.go","lineNumber":116,"sourceCode":"\n// write takes a writer and creates an archive with the snapshot metadata,\n// the snapshot itself, and adds some integrity checking information.\nfunc write(out io.Writer, metadata *raft.SnapshotMeta, snap io.Reader) error {\n\t// Start a new tarball.\n\tnow := time.Now()\n\tarchive := tar.NewWriter(out)\n\n\t// Create a hash list that we will use to write a SHA256SUMS file into\n\t// the archive.\n\thl := newHashList()\n\n\t// Encode the snapshot metadata, which we need to feed back during a\n\t// restore.\n\tmetaHash := hl.Add(\"meta.json\")\n\tvar metaBuffer bytes.Buffer\n\tenc := json.NewEncoder(&metaBuffer)\n\tif err := enc.Encode(metadata); err != nil {\n\t\treturn fmt.Errorf(\"failed to encode snapshot metadata: %v\", err)\n\t}\n\tif err := archive.WriteHeader(&tar.Header{\n\t\tName:    \"meta.json\",\n\t\tMode:    0600,\n\t\tSize:    int64(metaBuffer.Len()),\n\t\tModTime: now,\n\t}); err != nil {\n\t\treturn fmt.Errorf(\"failed to write snapshot metadata header: %v\", err)\n\t}\n\tif _, err := io.Copy(archive, io.TeeReader(&metaBuffer, metaHash)); err != nil {\n\t\treturn fmt.Errorf(\"failed to write snapshot metadata: %v\", err)\n\t}\n\n\t// Copy the snapshot data given the size from the metadata.\n\tsnapHash := hl.Add(\"state.bin\")\n\tif err := archive.WriteHeader(&tar.Header{\n\t\tName:    \"state.bin\",\n\t\tMode:    0600,","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/snapshot/archive.go#L98-L134","documentation":"write() encodes the snapshot metadata struct as JSON into meta.json before adding it to the tar archive. This error wraps the json.Encoder failure. It is rare because the metadata is a plain in-memory struct.","triggerScenarios":"enc.Encode(metadata) fails, typically from an unsupported type in the metadata struct (e.g. a channel or func field added by a version change) or an already-consumed/broken buffer writer.","commonSituations":"Upgrading the library and adding a non-serializable field to SnapshotMetadata, or memory/buffer issues.","solutions":["Ensure the metadata struct contains only JSON-serializable types","Fix the underlying buffer/writer error reported in the wrapped %v","Pin or update the library version to one compatible with your metadata shape"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := write(archive, metadata, snap); err != nil {\n    if strings.Contains(err.Error(), \"failed to encode snapshot metadata\") {\n        return fmt.Errorf(\"metadata not serializable: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep SnapshotMetadata fields JSON-serializable (no chan/func)","Add a round-trip json.Marshal test for metadata structs","Re-run encoding tests after library upgrades"],"tags":["json","serialization","snapshot"],"backgroundTag":"json-encode-failed","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"}