juicedata/juicefs · error

failed to read staging directory

Error message

failed to read staging directory

What it means

Wraps an os.Stat error on the writeback staging directory (<cache-dir>/rawstaging) during `juicefs umount --flush`; waitWritebackComplete polls this directory until all staging chunks are flushed. NotExist is treated as success (nothing staging); every other stat error (EACCES, EIO, ELOOP) is wrapped and aborts the unmount.

Source

Thrown at cmd/umount.go:143

					fmt.Println("\rAll staging chunks are flushed")
				} else {
					fmt.Printf("\r%s staging chunks are not flushed\n", humanize.IBytes(size))
				}
			}()
		}
	}
	return doUmount(mp, ctx.Bool("force"))
}

func waitWritebackComplete(stagingDir string) error {
	lastLeft := uint64(0)
	for {
		_, err := os.Stat(stagingDir)
		if err != nil {
			if os.IsNotExist(err) {
				return nil
			}
			return errors.Wrap(err, "failed to read staging directory")
		}
		start := time.Now()
		size, err := fileSizeInDir(stagingDir)
		if err != nil {
			if os.IsNotExist(err) {
				continue
			}
			return errors.Wrap(err, "failed to read staging directory")
		}
		if lastLeft == 0 {
			lastLeft = size
		}

		if size == 0 && lastLeft == 0 {
			return nil
		}

		speed := uint64(0)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Read the wrapped cause errno; fix permissions on the cache/rawstaging directory (`ls -ld <cache-dir>/rawstaging`)
2. Verify the volume hosting cache-dir is mounted and healthy
3. Point the mount's cache-dir to a healthy local path and remount before umount --flush
4. If the data is already flushed and the dir is broken, use umount without --flush or --force

Example fix

// before
juicefs umount /mnt/jfs --flush   # EACCES on /var/jfsCache/rawstaging
// after
sudo ls -ld /var/jfsCache/rawstaging && sudo chmod 755 /var/jfsCache
sudo juicefs umount /mnt/jfs --flush

staging := filepath.Join(cacheDir, "rawstaging")
if _, err := os.Stat(staging); err != nil && !os.IsNotExist(err) { return fmt.Errorf("staging dir unreadable: %w", err) }

if err := waitWritebackComplete(staging); err != nil {
	log.Printf("cannot check writeback staging: %v — verify cache dir health/permissions", err)
}

When it happens

Trigger: Running `juicefs umount <mp> --flush` on a volume mounted with `--writeback` where the staging directory exists but cannot be stat'd: permission changed on the cache directory, the cache dir is on a failed/unmounted volume, or a symlink loop / I/O error on the cache path.

Common situations: Cache directory on an external disk that was detached; permissions tightened on cache-dir (e.g. run as different user than mount); cache dir pointing into the FUSE mount itself causing I/O errors once the mount degrades.

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

• name is required
• Could not get a FileSystem
• Cannot get file system.
• Cannot create file system.
• renew token failed

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