juicedata/juicefs · error

failed to read checkpoint: %w

Error message

failed to read checkpoint: %w

What it means

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.

Source

Thrown at pkg/sync/checkpoint.go:252

	}
}

// Load loads checkpoint from object storage
func (m *CheckpointManager) Load() (*Checkpoint, error) {
	go m.cleanupCheckpointTmp()
	obj, err := m.dst.Get(ctx, m.checkpointKey, 0, -1)
	if err != nil {
		// head to wrap 404 as os.ErrNotExist
		if _, err := m.dst.Head(ctx, m.checkpointKey); os.IsNotExist(err) {
			return nil, err
		}
		return nil, err
	}
	defer obj.Close()

	data, err := io.ReadAll(obj)
	if err != nil {
		return nil, fmt.Errorf("failed to read checkpoint: %w", err)
	}

	var ckpt Checkpoint
	if err := json.Unmarshal(data, &ckpt); err != nil {
		return nil, fmt.Errorf("failed to unmarshal checkpoint: %w", err)
	}
	if ckpt.MultipartUploads == nil {
		ckpt.MultipartUploads = make(map[string]*multipartUploadState)
	}

	m.checkpoint = &ckpt
	m.multipartUploadStore.reset(ckpt.MultipartUploads)
	return &ckpt, nil
}

// Save saves checkpoint to object storage
func (m *CheckpointManager) Save(ckpt *Checkpoint) error {
	if ckpt.Config != nil && ckpt.Config.Dry {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Re-run the sync; if the checkpoint is unusable, delete the checkpoint object at the checkpoint key so a fresh checkpoint is created
2. Check network stability / increase timeouts to the destination object store
3. Verify the checkpoint object integrity (size, ETag) in the destination store; re-upload or remove it if truncated
4. Check destination storage backend health and permissions (logs of underlying error in %w cause)

Example fix

// before
data, err := io.ReadAll(obj)
if err != nil {
	return nil, fmt.Errorf("failed to read checkpoint: %w", err)
}
// after: fall back to starting fresh when the checkpoint is unreadable
data, err := io.ReadAll(obj)
if err != nil {
	logger.Warnf("checkpoint unreadable, starting fresh: %v", err)
	return &Manager{checkpoint: &Checkpoint{MultipartUploads: map[string]*multipartUploadState{}}}, nil
}

// Go: nothing to pre-validate for a stream read, but you can pre-check object existence/size
if obj, err := dst.Head(ctx, key); err != nil || obj.Size() == 0 {
	// treat as missing checkpoint, start fresh
}

ckpt, err := mgr.Load(ctx)
if err != nil {
	var unwrapped error = err
	if strings.Contains(unwrapped.Error(), "failed to read checkpoint") {
		logger.Warnf("checkpoint unreadable, starting fresh: %v", err)
		ckpt = nil // proceed without resume
	}
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• failed to unmarshal checkpoint: %w
• failed to put checkpoint: %w
• src read: %s
• open %s
• create %s

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