juicedata/juicefs · error

load meta format

Error message

load meta format

What it means

While loading metadata from the engine (m.Load inside a maintenance operation such as syncing slices), the stored volume format could not be read. The wrapped inner error carries the underlying cause from the metadata engine (connection failure, corrupted record, missing format).

Source

Thrown at pkg/meta/base.go:2572

			if needSyncVolumeStat && m.getFormat().TrashDays > 0 {
				trashAttr := Attr{Typ: TypeDirectory}
				if st := m.walk(ctx, TrashInode, "/.trash", &trashAttr, func(_ Context, ino Ino, _ string, a *Attr) {
					recordStat(ino, a)
				}); st != 0 {
					walkError = true
					logger.Errorf("Walk /.trash: %s", st)
				}
			}
		} else {
			nodes <- &node{inode, fpath, &attr}
			count = 1
		}
		nodeBar.SetTotal(count)
	}()

	format, err := m.Load(false)
	if err != nil {
		return errors.Wrap(err, "load meta format")
	}
	if opt.SyncDirStat && !format.DirStats {
		logger.Warn("dir stats is disabled, flag '--sync-dir-stat' will be ignored")
	}
	var lock sync.Mutex
	listSlices := func(inode Ino, path string) {
		lock.Lock()
		if _, ok := opt.Slices[inode]; ok {
			lock.Unlock()
			return
		}
		opt.Slices[inode] = []Slice{}
		lock.Unlock()
		rawSlices, st := m.en.doList(ctx, inode)
		if st != 0 {
			logger.Errorf("dolist %s: %s", path, st)
			return
		}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Verify the metadata URL with 'juicefs status <meta-url>' — it should print the volume format
2. Check connectivity/auth to the metadata engine (redis-cli ping, mysql client connect)
3. If the format key was lost, restore metadata from the latest backup (juicefs dump output) or re-format only if data loss is acceptable
4. Inspect the wrapped inner error for the exact engine-side cause and fix accordingly

Example fix

// before (wrong db index, empty format)
juicefs gc redis://127.0.0.1:6379/0
// load meta format: ... not found
// after (correct volume URL)
juicefs gc redis://127.0.0.1:6379/1

// verify metadata is healthy before maintenance ops
if err := exec.Command("juicefs", "status", metaURL).Run(); err != nil {
  // metadata unreachable or format missing; fix before running gc/dump
}

format, err := m.Load(false)
if err != nil {
  return errors.Wrap(err, "load meta format") // inspect wrapped cause; retry transient engine errors
}

When it happens

Trigger: Calling maintenance commands that trigger m.loadFormat (e.g. juicefs gc, fsck, slice sync paths) when the metadata engine is unreachable, the format record was deleted/corrupted, or the metadata URL points to an empty/foreign database.

Common situations: Wrong metadata URL typo (pointing at an empty Redis DB), Redis flushed or format key deleted, network partition to the metadata engine, corrupted SQL row after partial restore from backup.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• database %s is used by volume %s
• load setting: %s
• new session: %s
• Initialize: %s
• load user/group quotas: %w

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