{"record":{"id":"40e9e3500c6f0d12","repo":"juicedata/juicefs","slug":"failed-to-unmarshal-checkpoint-w","errorCode":null,"errorMessage":"failed to unmarshal checkpoint: %w","messagePattern":"failed to unmarshal checkpoint: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/sync/checkpoint.go","lineNumber":257,"sourceCode":"\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 {\n\t\treturn nil\n\t}\n\tm.saveMu.Lock()\n\tdefer m.saveMu.Unlock()\n\tif m.statsUpdater != nil {","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/sync/checkpoint.go#L239-L275","documentation":"Load() unmarshals the checkpoint bytes into the Checkpoint struct with encoding/json. This error wraps json.Unmarshal failures, meaning the checkpoint object was read but its content is not valid JSON or does not match the Checkpoint schema (e.g. wrong format, corrupted, or written by an incompatible version). Load treats the checkpoint as unusable and returns without setting m.checkpoint.","triggerScenarios":"Sync resumes and Load reads the object at m.checkpointKey, but json.Unmarshal fails because the object content is not a valid Checkpoint JSON document — file written by a different tool/format, schema drift between JuiceFS versions, or truncated/partial JSON from an interrupted Save.","commonSituations":"Upgrading JuiceFS between versions where Checkpoint fields changed; checkpoint object corrupted in the object store; user accidentally pointed the sync at an object that isn't a checkpoint; interrupted previous run left partial data.","solutions":["Delete/overwrite the stale checkpoint object so Sync starts fresh (or use the force-reset behavior to ignore the existing checkpoint)","Confirm the checkpoint was written by a compatible JuiceFS version; align client versions across workers","Inspect the object content at the checkpoint key to confirm it is valid JSON matching the Checkpoint schema"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate checkpoint JSON before handing it to Load-equivalent logic\ndata, _ := io.ReadAll(obj)\nif !json.Valid(data) {\n\t// invalid checkpoint: delete it or force a fresh start\n}","typeGuard":null,"tryCatchPattern":"ckpt, err := mgr.Load(ctx)\nif err != nil {\n\tif strings.Contains(err.Error(), \"failed to unmarshal checkpoint\") {\n\t\tlogger.Warnf(\"ignoring incompatible/corrupt checkpoint: %v\", err)\n\t\tckpt = nil\n\t}\n}","preventionTips":["Run mixed-version workers only with compatible JuiceFS versions","Never hand-edit or repurpose objects stored at the checkpoint key","Use force-reset when you know the existing checkpoint is from an incompatible run"],"tags":["json","checkpoint","unmarshal","resume"],"backgroundTag":"json-unmarshal-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"}