What causes "existing format is broken: %s" in juicedata/juicefs?

Inspect the stored format: redis-cli -n GET setting (key name from m.formatKey()); check whether it is valid JSON.

existing format is broken: %s

Error message

existing format is broken: %s

What it means

During format initialization (doInit), if the settings key already exists in Redis, its stored JSON is unmarshaled into the old Format. When that JSON cannot be parsed, this error is returned (pkg/meta/redis.go:345), signaling the volume's persisted format record in Redis is corrupted or was written by an incompatible tool. JuiceFS refuses to proceed to avoid mounting with a broken/unknown volume definition.

Source

Thrown at pkg/meta/redis.go:345

	})
	return err
}

func (m *redisMeta) Name() string {
	return "redis"
}

func (m *redisMeta) doInit(format *Format, force bool) error {
	ctx := Background()
	body, err := m.rdb.Get(ctx, m.setting()).Bytes()
	if err != nil && err != redis.Nil {
		return err
	}
	if err == nil {
		var old Format
		err = json.Unmarshal(body, &old)
		if err != nil {
			return fmt.Errorf("existing format is broken: %s", err)
		}
		if !old.DirStats && format.DirStats {
			// remove dir stats as they are outdated
			_, err := m.rdb.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
				pipe.Del(ctx, m.dirUsedInodesKey(), m.dirUsedSpaceKey())
				m.genLog(ctx, pipe, time.Now(), "INIT_ENABLE_DIRSTATS()")
				return nil
			})
			if err != nil {
				return errors.Wrap(err, "remove dir stats")
			}
		}
		if !old.UserGroupQuota && format.UserGroupQuota {
			// remove user group quota as they are outdated
			_, err := m.rdb.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
				pipe.Del(ctx, m.userQuotaKey(), m.userQuotaUsedSpaceKey(), m.userQuotaUsedInodesKey(),
					m.groupQuotaKey(), m.groupQuotaUsedSpaceKey(), m.groupQuotaUsedInodesKey())
				m.genLog(ctx, pipe, time.Now(), "INIT_ENABLE_USERGROUPQUOTA()")

View on GitHub (pinned to c9a67b23e8)

Solutions

Inspect the stored format: redis-cli -n <db> GET setting (key name from m.formatKey()); check whether it is valid JSON.
If the volume is disposable, delete the volume with juicefs rmr / flush the DB and re-run juicefs format.
If data must be kept, restore the format JSON from a backup (juicefs dump/backup) or reconstruct it to match the original volume settings, then retry.
Ensure no other application shares the same Redis DB index; use a dedicated DB number for the volume.

Example fix

// before: inspect
$ redis-cli -n 1 GET setting
"{broken..."  // not valid JSON
// after: restore from a backup dump or re-format an empty volume
$ juicefs dump redis://127.0.0.1:6379/1 meta.json
$ redis-cli -n 1 DEL setting
$ juicefs format redis://127.0.0.1:6379/1 myjfs

Defensive patterns

Strategy: validation

Validate before calling

// verify the stored format parses before initializing
val, _ := rdb.Get(ctx, "setting").Result()
var f juicefsFormat
if err := json.Unmarshal([]byte(val), &f); err != nil {
    return fmt.Errorf("volume format in Redis is corrupted: %w", err)
}

Try / catch

if _, err := juicefs.NewMeta("redis://..."); err != nil {
    if strings.Contains(err.Error(), "existing format is broken") {
        // do NOT proceed; restore from juicefs dump backup or re-format an empty volume
    }
    return err
}

Prevention

Never hand-edit the format key in Redis with redis-cli.
Give JuiceFS a dedicated Redis DB index so no other app overwrites its keys.
Keep regular juicefs dump backups so the format can be restored.
Avoid killing clients mid-format; re-format cleanly if interrupted.

When it happens

Trigger: Running juicefs mount / juicefs format / any meta init against a Redis where the setting key contains non-JSON data: manual edits to the key, partial writes from a crashed old client, data corruption, or the key being overwritten by another application sharing the same Redis DB.

Common situations: Someone hand-edited the format in redis-cli; the Redis DB index collides with another app that wrote its own data at the same key; a corrupted RDB/AOF restore; an ancient or third-party client wrote a structurally different format blob.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

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