{"record":{"id":"1a20f3448c8f9412","repo":"juicedata/juicefs","slug":"failed-to-put-checkpoint-w","errorCode":null,"errorMessage":"failed to put checkpoint: %w","messagePattern":"failed to put checkpoint: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/sync/checkpoint.go","lineNumber":307,"sourceCode":"\tdstDelayDelMu.Lock()\n\tckpt.DstDelayDel = append([]string(nil), dstDelayDel...)\n\tdstDelayDelMu.Unlock()\n\tdata, err := json.Marshal(ckpt)\n\tm.multipartUploadStore.RUnlock()\n\tfor _, state := range ckpt.PrefixState {\n\t\tstate.RUnlock()\n\t}\n\tckpt.Unlock()\n\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to marshal checkpoint: %w\", err)\n\t}\n\n\tlogger.Debugf(\"Saving checkpoint with %d prefixes, copied: %d, failed: %d\",\n\t\tprefixCount, ckpt.Stats.Copied, ckpt.Stats.Failed)\n\treader := bytes.NewReader(data)\n\tif err := m.dst.Put(ctx, m.checkpointKey, reader); err != nil {\n\t\treturn fmt.Errorf(\"failed to put checkpoint: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// ValidateConfig checks if checkpoint config matches current config\nfunc (m *CheckpointManager) ValidateConfig(current *Config) bool {\n\told := m.checkpoint.Config\n\n\t// Must match fields\n\tif old.Start != current.Start || old.End != current.End {\n\t\tlogger.Warnf(\"Checkpoint config mismatch: start/end, old: %q/%q, current: %q/%q\", old.Start, old.End, current.Start, current.End)\n\t\treturn false\n\t}\n\n\tif !slices.Equal(old.Include, current.Include) || !slices.Equal(old.Exclude, current.Exclude) {\n\t\tlogger.Warnf(\"Checkpoint config mismatch: include/exclude, old: %v/%v, current: %v/%v\", old.Include, old.Exclude, current.Include, current.Exclude)\n\t\treturn false","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/sync/checkpoint.go#L289-L325","documentation":"Save() writes the marshalled checkpoint bytes to the destination storage under m.checkpointKey via dst.Put. This error wraps a Put failure, meaning the checkpoint could not be stored (network error, permission denied, bucket issues, storage backend 5xx). The checkpoint remains unsaved for this round and progress resumption may fall back to the last successful save.","triggerScenarios":"Periodic Save during a running Sync (or tests calling Save directly) where the destination object store rejects the Put: transient network failure, expired/insufficient credentials, bucket not writable, rate limiting, or the destination is offline.","commonSituations":"Long-running sync across unstable network to S3/OSS; IAM policy lacking PutObject on the checkpoint prefix; disk full when dst is a local path; object-store throttling on frequent checkpoint saves.","solutions":["Retry the sync/save; Put failures are often transient — reduce checkpoint frequency if throttled","Verify write credentials/permissions on the destination for the checkpoint key path","Check destination storage availability and error details in the wrapped cause (%w)","Use --dry-run or a smaller checkpoint interval to isolate whether the checkpoint key path itself is the problem"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-check write access to the destination\nif _, err := m.dst.Head(ctx, m.checkpointKey); err != nil && !isNotFound(err) {\n\t// destination may be misconfigured/unwritable; fix credentials before starting sync\n}","typeGuard":null,"tryCatchPattern":"if err := mgr.Save(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"failed to put checkpoint\") {\n\t\ttime.Sleep(backoff)\n\t\t_ = mgr.Save(ctx) // retry transient Put failures\n\t}\n}","preventionTips":["Grant the destination credentials PutObject permission on the sync prefix","Reduce checkpoint save frequency to avoid object-store throttling","Monitor destination bucket availability and disk space (for file:// destinations)"],"tags":["object-storage","checkpoint","network","write"],"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-14T00:17:10.932Z"}