{"record":{"id":"fecbcf7511293c31","repo":"juicedata/juicefs","slug":"failed-to-write-segment-type-s-w","errorCode":null,"errorMessage":"failed to write segment type %s : %w","messagePattern":"failed to write segment type (.+?) : %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/backup.go","lineNumber":331,"sourceCode":"\t\t\treturn uint64(len(b.Dirstats))\n\t\tcase segTypeQuota:\n\t\t\treturn uint64(len(b.Quotas) + len(b.UserQuotas) + len(b.GroupQuotas))\n\t\tcase segTypeParent:\n\t\t\treturn uint64(len(b.Parents))\n\t\tcase segTypeChangeLog:\n\t\t\treturn uint64(len(b.Changelogs))\n\t\t}\n\t\treturn 0\n\t}\n}\n\nfunc (s *BakSegment) Marshal(w io.Writer) (int, error) {\n\tif s == nil || s.val == nil {\n\t\treturn 0, fmt.Errorf(\"segment %s is nil\", s)\n\t}\n\n\tif err := binary.Write(w, binary.BigEndian, s.typ); err != nil {\n\t\treturn 0, fmt.Errorf(\"failed to write segment type %s : %w\", s, err)\n\t}\n\tdata, err := proto.Marshal(s.val)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"failed to marshal segment message %s : %w\", s, err)\n\t}\n\ts.len = uint64(len(data))\n\tif err := binary.Write(w, binary.BigEndian, s.len); err != nil {\n\t\treturn 0, fmt.Errorf(\"failed to write segment length %s: %w\", s, err)\n\t}\n\n\tif n, err := w.Write(data); err != nil || n != len(data) {\n\t\treturn 0, fmt.Errorf(\"failed to write segment data %s: err %w, write len %d, expect len %d\", s, err, n, len(data))\n\t}\n\n\treturn binary.Size(s.typ) + binary.Size(s.len) + len(data), nil\n}\n\nfunc (s *BakSegment) Unmarshal(r io.Reader) error {","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/backup.go#L313-L349","documentation":"BakSegment.Marshal writes the 4-byte big-endian segment type as the first field of each segment record. This error wraps the underlying write failure from binary.Write into the segment's writer, meaning the destination writer (typically the buffered writer over the backup file) rejected the write.","triggerScenarios":"The target file's write fails mid-backup: disk full, device error, file closed early, broken pipe on a piped/network writer, permissions revoked, or quota exceeded while `juicefs dump` streams segments.","commonSituations":"Dumping a large metadata tree to a full partition; writing to an NFS/S3-fuse mount that dropped; piping dump output (e.g. `juicefs dump ... | ssh`) where the remote end dies; running out of disk quota mid-write.","solutions":["Inspect the wrapped %w error for the root cause (ENOSPC, EPIPE, EACCES) and fix storage: free space, restore permissions, or reconnect the target.","Re-run the dump after fixing; the backup file is likely truncated/incomplete and must be rewritten from scratch.","If piping, verify the consumer process stayed alive and add pipefail so a dead consumer aborts the dump rather than silently truncating.","Write to a local staging file with sufficient free space, then copy to final destination, to avoid mid-stream failures on flaky mounts."],"exampleFix":"// before: piping dump straight to a remote sink\njuicefs dump meta://... | ssh host 'cat > meta.backup'\n\n// after: stage locally, verify, then transfer\njuicefs dump meta://... /local/meta.backup\nif ! verifyFooter /local/meta.backup; then echo \"dump failed\"; exit 1; fi\nscp /local/meta.backup host:","handlingStrategy":"fallback","validationCode":"st, err := out.Stat()\nif err == nil && st.Size()+estimateBytes > st.Sys().(*syscall.Stat_t).Blocks*512 { /* disk nearly full */ }\nif freeDiskSpace(targetDir) < estimatedBackupSize { return errors.New(\"insufficient space for backup\") }","typeGuard":"func writerAlive(w io.Writer) bool {\n    c, ok := w.(interface{ Check() error })\n    return !ok || c.Check() == nil\n}","tryCatchPattern":"if _, err := seg.Marshal(bw); err != nil {\n    if isEPIPE(err) || isENOSPC(err) {\n        os.Remove(backupPath) // discard incomplete backup\n        return fmt.Errorf(\"backup write failed, target unusable: %w\", err)\n    }\n    return err\n}","preventionTips":["Check free disk space before starting a large dump.","Avoid piping backup output over fragile transports; stage locally first.","Delete incomplete backup files on write failure so they are never restored.","Monitor storage errors on the destination mount (NFS/S3-fuse) during long dumps."],"tags":["io","backup","write-failed","disk-full"],"backgroundTag":"file-write-failed","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}