juicedata/juicefs · error

DumpMeta error

Error message

DumpMeta error: %v

What it means

This message is produced in redisMeta.dump (DumpMeta) as a panic-recovery fallback: if dump panics with a non-error value, it is converted into err = errors.Errorf("DumpMeta error: %v", p) and returned. Callers of DumpMeta therefore see this wrapped message whenever the dump implementation hits an unrecovered panic — a programming/invariant bug in the dump path rather than an ordinary operational failure.

Solutions

  1. Report the panic (with debug.PrintStack output, which is printed) to JuiceFS with the version and meta type; this path indicates a bug.
  2. Capture the stack trace and check release notes for a newer version fixing dump panics; upgrade the client.
  3. Work around by taking a Redis RDB/AOF backup instead of a JSON dump if dump is consistently panicking.
  4. Verify metadata integrity (gc/repair) in case the panic stems from corrupt records.
Defensive patterns

Strategy: try-catch

Validate before calling

// No caller-side validation prevents an internal panic; capture diagnostics:
err := juicefs.Dump(ctx, meta, w, &meta.DumpOption{KeepSecret: false})

Try / catch

if err := juicefs.Dump(ctx, meta, f, opt); err != nil {
    if strings.Contains(err.Error(), "DumpMeta error") {
        logger.Errorf("dump panicked, save stack + version for bug report: %v", err)
        // fall back to engine-native backup (RDB/AOF, SQL dump)
    }
    return err
}

Prevention

When it happens

Trigger: Running `juicefs dump` (or backup) against a Redis metadata engine when the dump goroutine panics (e.g. nil dereference on an unexpected metadata record shape, index-out-of-range while iterating dumped entries); the deferred recover in redisMeta.dump converts the panic into this returned error.

Common situations: Dumping a volume whose metadata contains records written by a newer incompatible client; corrupted metadata entries; genuine bugs in a specific JuiceFS version's dump code.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at pkg/meta/redis.go:4952

		if i != len(entries)-1 {
			bwWrite(",")
		}
		if showProgress != nil {
			showProgress(0, 1)
		}
	}
	bwWrite(fmt.Sprintf("\n%s}\n%s}", strings.Repeat(jsonIndent, depth+1), strings.Repeat(jsonIndent, depth)))
	return nil
}

func (m *redisMeta) DumpMeta(w io.Writer, root Ino, threads int, keepSecret, fast, skipTrash bool) (err error) {
	defer func() {
		if p := recover(); p != nil {
			debug.PrintStack()
			if e, ok := p.(error); ok {
				err = e
			} else {
				err = errors.Errorf("DumpMeta error: %v", p)
			}
		}
	}()
	ctx := Background()
	var lastChangelog int64
	if m.getFormat().ChangeLog {
		lastLog, err := m.rdb.Get(ctx, m.txnLastLog()).Int64()
		if err == nil {
			lastChangelog = lastLog
		}
	}
	zs, err := m.rdb.ZRangeWithScores(ctx, m.delfiles(), 0, -1).Result()
	if err != nil {
		return err
	}
	dels := make([]*DumpedDelFile, 0, len(zs))
	for _, z := range zs {
		parts := strings.Split(z.Member.(string), ":")

View on GitHub (pinned to c9a67b23e8)