juicedata/juicefs · error

update format

Error message

update format

What it means

Returned from redisMeta.doInit when format.update(&old, force) — the function that validates and persists the new volume format settings against the previously stored format — fails. This is the final step of applying a format change during mount; failures typically mean the requested change conflicts with the existing format (e.g. incompatible settings without --force) or persisting the updated JSON to Redis failed.

Source

Thrown at pkg/meta/redis.go:371

			})
			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()")
				return nil
			})
			if err != nil {
				return errors.Wrap(err, "remove user group quota")
			}
		}
		if err = format.update(&old, force); err != nil {
			return errors.Wrap(err, "update format")
		}
	}

	data, err := json.MarshalIndent(format, "", "")
	if err != nil {
		return fmt.Errorf("json: %s", err)
	}
	ts := time.Now().Unix()
	attr := &Attr{
		Typ:    TypeDirectory,
		Atime:  ts,
		Mtime:  ts,
		Ctime:  ts,
		Nlink:  2,
		Length: 4 << 10,
		Parent: RootInode,
	}
	if format.TrashDays > 0 {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Unwrap the underlying error from format.update; if it is a compatibility rejection, use `juicefs config <meta-url> --force` deliberately or revert the setting.
2. Compare the stored format (`juicefs status <meta-url>`) with the requested settings to find the conflicting field.
3. Retry if the cause was a transient Redis write failure.
4. Upgrade/downgrade clients to a consistent version before changing the format.

// Compare desired vs stored format before mounting:
st, _ := juicefs.Status(ctx, metaUrl)
// ensure changed fields (storage, bucket, capacity) are allowed or pass force

if err := doInit(ctx, format); err != nil {
    if strings.Contains(err.Error(), "update format") {
        // inspect incompatible field and either revert or use juicefs config --force
    }
    return err
}

When it happens

Trigger: Mounting with client-side settings or a config change where format.update rejects the modification (incompatible capacity, storage, or secret change without force=true), or the underlying save of the updated format (e.g. a Redis write) returns an error.

Common situations: Changing immutable format fields (e.g. storage backend, bucket) without `juicefs config --force`; mixed old/new client versions disagreeing on format; Redis write failure while persisting the format hash.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• scan trash slices: %s
• remove dir stats
• remove user group quota
• database %s is used by volume %s
• load setting: %s

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