{"record":{"id":"c6abac094ba81751","repo":"juicedata/juicefs","slug":"failed-to-read-checkpoint-w","errorCode":null,"errorMessage":"failed to read checkpoint: %w","messagePattern":"failed to read checkpoint: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/sync/checkpoint.go","lineNumber":252,"sourceCode":"\t}\n}\n\n// Load loads checkpoint from object storage\nfunc (m *CheckpointManager) Load() (*Checkpoint, error) {\n\tgo m.cleanupCheckpointTmp()\n\tobj, err := m.dst.Get(ctx, m.checkpointKey, 0, -1)\n\tif err != nil {\n\t\t// head to wrap 404 as os.ErrNotExist\n\t\tif _, err := m.dst.Head(ctx, m.checkpointKey); os.IsNotExist(err) {\n\t\t\treturn nil, err\n\t\t}\n\t\treturn nil, err\n\t}\n\tdefer obj.Close()\n\n\tdata, err := io.ReadAll(obj)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read checkpoint: %w\", err)\n\t}\n\n\tvar ckpt Checkpoint\n\tif err := json.Unmarshal(data, &ckpt); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to unmarshal checkpoint: %w\", err)\n\t}\n\tif ckpt.MultipartUploads == nil {\n\t\tckpt.MultipartUploads = make(map[string]*multipartUploadState)\n\t}\n\n\tm.checkpoint = &ckpt\n\tm.multipartUploadStore.reset(ckpt.MultipartUploads)\n\treturn &ckpt, nil\n}\n\n// Save saves checkpoint to object storage\nfunc (m *CheckpointManager) Save(ckpt *Checkpoint) error {\n\tif ckpt.Config != nil && ckpt.Config.Dry {","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/sync/checkpoint.go#L234-L270","documentation":"Load() fetches the checkpoint object from the destination storage and reads its full content into memory. This error wraps any failure returned by io.ReadAll while draining the object stream, meaning the object handle was obtained but its bytes could not be fully read (truncated object, network interruption, storage backend I/O failure). The Sync run cannot resume from a partially readable checkpoint, so Load aborts with this wrapped cause.","triggerScenarios":"Calling Sync with --checkpoint-on (or resume behavior) triggers Load; the checkpoint object exists at m.checkpointKey on dst but io.ReadAll(obj) fails — e.g. the object was truncated/corrupted in the object store, the connection dropped mid-download, or the storage backend returned an I/O error while streaming.","commonSituations":"Resuming a large sync job after a network blip; checkpoint written by an older/failed run whose Put was interrupted; object-store (S3/OSS) 5xx or timeout during GET body read; disk-backed storage with full disk.","solutions":["Re-run the sync; if the checkpoint is unusable, delete the checkpoint object at the checkpoint key so a fresh checkpoint is created","Check network stability / increase timeouts to the destination object store","Verify the checkpoint object integrity (size, ETag) in the destination store; re-upload or remove it if truncated","Check destination storage backend health and permissions (logs of underlying error in %w cause)"],"exampleFix":"// before\ndata, err := io.ReadAll(obj)\nif err != nil {\n\treturn nil, fmt.Errorf(\"failed to read checkpoint: %w\", err)\n}\n// after: fall back to starting fresh when the checkpoint is unreadable\ndata, err := io.ReadAll(obj)\nif err != nil {\n\tlogger.Warnf(\"checkpoint unreadable, starting fresh: %v\", err)\n\treturn &Manager{checkpoint: &Checkpoint{MultipartUploads: map[string]*multipartUploadState{}}}, nil\n}","handlingStrategy":"try-catch","validationCode":"// Go: nothing to pre-validate for a stream read, but you can pre-check object existence/size\nif obj, err := dst.Head(ctx, key); err != nil || obj.Size() == 0 {\n\t// treat as missing checkpoint, start fresh\n}","typeGuard":null,"tryCatchPattern":"ckpt, err := mgr.Load(ctx)\nif err != nil {\n\tvar unwrapped error = err\n\tif strings.Contains(unwrapped.Error(), \"failed to read checkpoint\") {\n\t\tlogger.Warnf(\"checkpoint unreadable, starting fresh: %v\", err)\n\t\tckpt = nil // proceed without resume\n\t}\n}","preventionTips":["Ensure stable connectivity to the destination object store during resume","Avoid interrupting Save mid-Put; rely on atomic/retryable uploads","Monitor object-store health (5xx/timeout metrics) before resuming large syncs"],"tags":["io","checkpoint","object-storage","resume"],"backgroundTag":"file-read-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"}