{"record":{"id":"871ff62912ce43f0","repo":"hashicorp/nomad","slug":"failed-to-write-snapshot-data-header-v","errorCode":null,"errorMessage":"failed to write snapshot data header: %v","messagePattern":"failed to write snapshot data header: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/snapshot/archive.go","lineNumber":138,"sourceCode":"\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,\n\t\tSize:    metadata.Size,\n\t\tModTime: now,\n\t}); err != nil {\n\t\treturn fmt.Errorf(\"failed to write snapshot data header: %v\", err)\n\t}\n\tif _, err := io.CopyN(archive, io.TeeReader(snap, snapHash), metadata.Size); err != nil {\n\t\treturn fmt.Errorf(\"failed to write snapshot metadata: %v\", err)\n\t}\n\n\t// Create a SHA256SUMS file that we can use to verify on restore.\n\tvar shaBuffer bytes.Buffer\n\tif err := hl.Encode(&shaBuffer); err != nil {\n\t\treturn fmt.Errorf(\"failed to encode snapshot hashes: %v\", err)\n\t}\n\tif err := archive.WriteHeader(&tar.Header{\n\t\tName:    \"SHA256SUMS\",\n\t\tMode:    0600,\n\t\tSize:    int64(shaBuffer.Len()),\n\t\tModTime: now,\n\t}); err != nil {\n\t\treturn fmt.Errorf(\"failed to write snapshot hashes header: %v\", err)\n\t}","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/snapshot/archive.go#L120-L156","documentation":"write() writes the state.bin tar header sized from metadata.Size before copying the snapshot data. This error wraps a failure writing that header. It means the archive sink rejected the header write for the snapshot data entry.","triggerScenarios":"archive.WriteHeader for state.bin fails: underlying writer error (disk full, closed writer, broken pipe) or invalid metadata.Size (negative size header).","commonSituations":"metadata.Size corrupted or negative due to a bad metadata source; destination storage failure mid-snapshot.","solutions":["Validate metadata.Size is a correct non-negative value matching the snapshot data length","Check destination disk space and writer health","Inspect the wrapped error for the root cause"],"exampleFix":"// before\nif err := archive.WriteHeader(&tar.Header{Name: \"state.bin\", Size: metadata.Size, ...}); err != nil { ... }\n// after\nif metadata.Size < 0 {\n    return fmt.Errorf(\"invalid snapshot size: %d\", metadata.Size)\n}\nif err := archive.WriteHeader(&tar.Header{Name: \"state.bin\", Size: metadata.Size, ...}); err != nil { ... }","handlingStrategy":"validation","validationCode":"if metadata.Size < 0 {\n    return fmt.Errorf(\"invalid snapshot size %d\", metadata.Size)\n}","typeGuard":null,"tryCatchPattern":"if err := write(archive, metadata, snap); err != nil {\n    if strings.Contains(err.Error(), \"failed to write snapshot data header\") {\n        return fmt.Errorf(\"bad snapshot header/destination: %w\", err)\n    }\n    return err\n}","preventionTips":["Always populate metadata.Size from the real data length","Reject negative or zero sizes for non-empty snapshots","Verify the sink writer is healthy before starting"],"tags":["tar","io","disk"],"backgroundTag":"disk-full","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"}