expect file size=%d unmatch remote report size=%d, need refr

Error message

expect file size=%d unmatch remote report size=%d, need refresh cache

What it means

checkTotalBytes compares the server-reported total (from Content-Range) against the locally cached/expected size in d.params.Size; a mismatch means the remote file changed since metadata was cached. The downloader cancels itself (setErr + cancel) because all chunk ranges were planned from the stale size — the message even says 'need refresh cache'.

Source

Thrown at internal/net/request.go:508

		total := int64(-1)

		// Checking for whether a numbered total exists
		// If one does not exist, we will assume the total to be -1, undefined,
		// and sequentially download each chunk until hitting a 416 error
		totalStr := parts[len(parts)-1]
		if totalStr != "*" {
			total, err = strconv.ParseInt(totalStr, 10, 64)
			if err != nil {
				err = fmt.Errorf("failed extracting file size")
			}
		} else {
			err = fmt.Errorf("file size unknown")
		}

		totalBytes = total
	}
	if totalBytes != d.params.Size && err == nil {
		err = fmt.Errorf("expect file size=%d unmatch remote report size=%d, need refresh cache", d.params.Size, totalBytes)
	}
	if err != nil {
		// _ = d.interrupt()
		d.setErr(err)
		d.cancel(err)
	}
	return err

}

func (d *downloader) incrWritten(n int64) {
	d.m.Lock()
	defer d.m.Unlock()

	d.written += n
}

// getErr is a thread-safe getter for the error object

View on GitHub (pinned to 843d9dc814)

Solutions

Refresh the directory listing / cached metadata for that file, then retry the download.
Implement the suggested cache invalidation: evict the file's cached size on this error and re-fetch metadata.
Retry the download after refresh — chunk planning will use the new size.
If it recurs constantly, check whether two processes keep overwriting the remote file.

Defensive patterns

Strategy: retry

Type guard

strings.Contains(err.Error(), "need refresh cache")

Try / catch

err := download()
if err != nil && strings.Contains(err.Error(), "need refresh cache") {
    op.InvalidateCache(path)      // evict stale size
    _, _ = op.RefreshDirMetadata(ctx, path)
    err = retryDownload()         // replan chunks with fresh size
}

Prevention

Invalidate cached file metadata for files that failed with size mismatch before retrying.
Set sensible TTLs on listing caches for frequently-updated remote folders.
Refresh metadata right before large downloads of volatile files.

When it happens

Trigger: File replaced/updated upstream (different size) between when alist cached its metadata and the ranged download; cached size from an old listing; copy/overwrite happening concurrently on the remote.

Common situations: Remote drive re-uploaded or versioned the file; user downloads right after an upstream edit; long-lived caches in database listing records.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/e227f6da230e0a5a. Report an issue: GitHub.