juicedata/juicefs · error

stat fs: %v

Error message

stat fs: %v

What it means

`juicefs status` calls StatFS on the root inode to report space usage. StatFS returns an errno; if that errno is non-zero (not the success sentinel 0), Status wraps it as 'stat fs'. It means the metadata engine could not compute total/available space or inode counts.

Source

Thrown at pkg/meta/status.go:66

}

// Status retrieves the status of the filesystem
func Status(ctx context.Context, m Meta, trash bool, sections *Sections) error {
	format, err := m.Load(true)
	if err != nil {
		return fmt.Errorf("load setting: %v", err)
	}
	format.RemoveSecret()

	sessions, err := m.ListSessions()
	if err != nil {
		return fmt.Errorf("list sessions: %v", err)
	}

	stat := &Statistic{}
	var totalSpace uint64
	if err = m.StatFS(Background(), RootInode, &totalSpace, &stat.AvailableSpace, &stat.UsedInodes, &stat.AvailableInodes); err != syscall.Errno(0) {
		return fmt.Errorf("stat fs: %v", err)
	}
	stat.UsedSpace = totalSpace - stat.AvailableSpace

	if trash {
		progress := utils.NewProgress(false)
		defer progress.Done()
		trashFileSpinner := progress.AddDoubleSpinner("Trash Files")
		pendingDeletedFileSpinner := progress.AddDoubleSpinner("Pending Deleted Files")
		trashSlicesSpinner := progress.AddDoubleSpinner("Trash Slices")
		pendingDeletedSlicesSpinner := progress.AddDoubleSpinner("Pending Deleted Slices")
		err = m.ScanDeletedObject(
			WrapContext(ctx),
			func(ss []Slice, _ int64) (bool, error) {
				for _, s := range ss {
					trashSlicesSpinner.IncrInt64(int64(s.Size))
				}
				return false, nil
			},

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Read the wrapped errno: EIO/ENOENT suggests metadata damage; ETIMEDOUT/timeout suggests backend load.
2. Retry when the backend is less loaded; check redis latency doctor / mysql slow queries.
3. If ENOENT on root inode, the volume metadata is damaged — restore from a `juicefs dump` backup.
4. Ensure the client version is compatible with the volume (old client reading metadata written by a newer one); upgrade JuiceFS.

if err := execStatus(metaURL); err != nil && strings.Contains(err.Error(), "stat fs") {
    // retry once after backend settles, then check metadata integrity
    time.Sleep(5 * time.Second)
    if err := execStatus(metaURL); err != nil { log.Fatalf("metadata may be damaged, restore from dump: %v", err) }
}

When it happens

Trigger: Running `juicefs status META-URL` when Meta.StatFS returns an errno: metadata inconsistency for the root inode, backend timeout under load, or an engine-specific failure computing used space.

Common situations: Querying a volume with a corrupted/damaged metadata root entry; backend saturated (Redis blocked, DB long transaction) causing timeouts; extremely large inode counts making the stat scan slow and triggering timeouts on flaky networks.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• list sessions: %v
• changelog is not enabled, use `juicefs config %s --changelog
• clone failed: %v
• compact [%d:%s] error: %s
• database %s is used by volume %s

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