{"record":{"id":"c897a62b2b45b65f","repo":"hashicorp/nomad","slug":"failed-to-write-snapshot-file-v","errorCode":null,"errorMessage":"failed to write snapshot file: %v","messagePattern":"failed to write snapshot file: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/snapshot/snapshot.go","lineNumber":124,"sourceCode":"\tdefer func() {\n\t\tif keep {\n\t\t\treturn\n\t\t}\n\n\t\tif err := os.Remove(archive.Name()); err != nil {\n\t\t\tlogger.Error(\"Failed to clean up temp snapshot\", \"error\", err)\n\t\t}\n\t}()\n\n\thash := sha256.New()\n\tout := io.MultiWriter(hash, archive)\n\n\t// Wrap the file writer in a gzip compressor.\n\tcompressor := gzip.NewWriter(out)\n\n\t// Write the archive.\n\tif err := write(compressor, metadata, snap); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to write snapshot file: %v\", err)\n\t}\n\n\t// Finish the compressed stream.\n\tif err := compressor.Close(); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to compress snapshot file: %v\", err)\n\t}\n\n\t// Sync the compressed file and rewind it so it's ready to be streamed\n\t// out by the caller.\n\tif err := archive.Sync(); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to sync snapshot: %v\", err)\n\t}\n\tif _, err := archive.Seek(0, 0); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to rewind snapshot: %v\", err)\n\t}\n\n\tchecksum := \"sha-256=\" + base64.StdEncoding.EncodeToString(hash.Sum(nil))\n","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/snapshot/snapshot.go#L106-L142","documentation":"writeSnapshot wraps errors from write(), which serializes the snapshot metadata and FSM state into the gzip-wrapped archive file. This covers both gzip-compression write failures and the underlying file/disk write errors that occur while producing the snapshot archive. It is raised from New/NewFromFSM before the compressed stream is finalized.","triggerScenarios":"New or NewFromFSM where write(compressor, metadata, snap) returns an error: disk full while writing, I/O error on the temp file, the underlying sink's write() (snapshot store or FSM persist) failing, or gzip writer errors from the underlying writer.","commonSituations":"Disk fills during snapshot creation on the temp volume; storage backend (local store or cloud) returns an I/O error; FSM persist callback errors propagate up wrapped as this message.","solutions":["Check free disk space on the temp filesystem and the snapshot storage backend.","Inspect the wrapped cause (%v) — it names the actual failing write; fix that underlying storage/FSM error.","Verify the FSM Persist implementation and its sink are healthy (permissions, backend availability).","Re-run snapshot creation after freeing space or repairing storage; failures here leave the temp file cleaned up automatically."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"func diskHasSpace(min uint64) error {\n\tvar st syscall.Statfs_t\n\tif err := syscall.Statfs(os.TempDir(), &st); err != nil { return err }\n\tif uint64(st.Bavail)*uint64(st.Bsize) < min { return fmt.Errorf(\"low disk on %s\", os.TempDir()) }\n\treturn nil\n}\n// call diskHasSpace(100<<20) before snapshot.New","typeGuard":null,"tryCatchPattern":"snap, err := snapshot.New(...)\nif err != nil && strings.Contains(err.Error(), \"failed to write snapshot file\") {\n\t// err's wrapped cause names the real write failure\n\tlogger.Error(\"snapshot write failed\", \"err\", err)\n\treturn err\n}","preventionTips":["Keep headroom (e.g. >2x largest expected snapshot) on the temp volume.","Alert on disk usage before it reaches full.","Validate FSM Persist works with a small synthetic sink in tests.","Read the wrapped cause, not just the wrapper, when triaging."],"tags":["filesystem","io","snapshot","disk-full"],"backgroundTag":"snapshot-write-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"}