juicedata/juicefs · error

failed to handle %d objects

Error message

failed to handle %d objects

What it means

Returned at the end of `juicefs sync` when the failed counter shows objects that were not successfully handled (or totals exceed handled counts). The checkpoint is saved first so a re-run resumes at the failed objects; the count reports how many need attention.

Source

Thrown at pkg/sync/sync.go:2304

			if deleted != nil {
				msg += fmt.Sprintf(", deleted: %d", deleted.Current())
			}
			if failed != nil {
				msg += fmt.Sprintf(", failed: %d", failed.Current())
			}
			if total-handled.Current() > 0 {
				msg += fmt.Sprintf(", lost: %d", total-handled.Current())
			}
			logger.Info(msg)

			if failed != nil {
				if n := failed.Current(); n > 0 || total > handled.Current() {
					if checkpointMgr != nil {
						if e := checkpointMgr.Save(checkpointMgr.checkpoint); e != nil {
							logger.Warnf("Failed to save checkpoint after failure: %v", e)
						}
					}
					return fmt.Errorf("failed to handle %d objects", n+total-handled.Current())
				}
			}
			if checkpointMgr != nil && !config.Dry {
				if e := try(3, func() error {
					return checkpointMgr.DeleteCheckpoint()
				}); e != nil {
					logger.Warnf("Failed to delete checkpoint after completion: %v", e)
				}
			}
		} else {
			sendStats(config.Manager, workerUploads)
			for len(srcDelayDel) > 0 {
				sendStats(config.Manager, workerUploads)
			}
			logger.Infof("This worker process has already completed its tasks")
		}
		return nil
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Re-run the same sync command; it resumes from the checkpoint and retries failures
2. Inspect sync logs for the per-object errors behind the count

When it happens

Trigger: Thrown at pkg/sync/sync.go:2304 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/7c49dce3732f48ca. Report an issue: GitHub.