{"record":{"id":"0003522484f90ba2","repo":"hashicorp/nomad","slug":"failed-to-sync-snapshot-v","errorCode":null,"errorMessage":"failed to sync snapshot: %v","messagePattern":"failed to sync snapshot: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/snapshot/snapshot.go","lineNumber":135,"sourceCode":"\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\n\tkeep = true\n\treturn &Snapshot{archive, metadata.Index, checksum}, nil\n}\n\n// Index returns the index of the snapshot. This is safe to call on a nil\n// snapshot, it will just return 0.\nfunc (s *Snapshot) Index() uint64 {\n\tif s == nil {\n\t\treturn 0\n\t}\n\treturn s.index","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/snapshot/snapshot.go#L117-L153","documentation":"writeSnapshot calls archive.Sync() to flush the compressed snapshot file to stable storage before handing it to the caller. If the OS cannot sync the file (fsync failure), snapshot creation aborts with this error, since an unsynced snapshot cannot be trusted for later re-reading.","triggerScenarios":"New or NewFromFSM where archive.Sync() returns an error: disk I/O errors (EIO), filesystem errors, disk full manifests at sync time, or underlying device problems on the temp volume.","commonSituations":"Failing or over-subscribed disks (especially in VMs/cloud instances); NFS or unusual filesystems for TMPDIR that don't support fsync well; kernel-level storage errors under heavy load.","solutions":["Check dmesg/system logs for storage device errors (EIO) around the failure time.","Ensure the temp directory is on a local, reliable filesystem rather than NFS or flaky network storage (set TMPDIR accordingly).","Verify disk health (SMART) and free space on the volume holding the temp files.","Retry the snapshot after storage is healthy; the temp file from the failed attempt is cleaned up in Close()."],"exampleFix":"// before: TMPDIR on NFS → fsync errors\n// after\nexport TMPDIR=/var/lib/myapp/tmp   # local disk\nmkdir -p $TMPDIR","handlingStrategy":"validation","validationCode":"// require a local filesystem for temp files\nif isNetworkMount(os.TempDir()) {\n\treturn fmt.Errorf(\"TMPDIR %q is a network mount; use local disk\", os.TempDir())\n}","typeGuard":null,"tryCatchPattern":"snap, err := snapshot.New(...)\nif err != nil && strings.Contains(err.Error(), \"failed to sync snapshot\") {\n\tlogger.Error(\"fsync of snapshot temp failed; check storage health\", \"err\", err)\n\treturn err\n}","preventionTips":["Use local (not NFS) filesystems for TMPDIR.","Monitor dmesg/storage errors on nodes running snapshot creation.","Check disk SMART health after any sync failure.","Leave free space so fsync metadata updates don't hit ENOSPC."],"tags":["filesystem","fsync","io","snapshot"],"backgroundTag":"fsync-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"}