incompatible metadata version: %d; please upgrade the client

Error message

incompatible metadata version: %d; please upgrade the client

What it means

CheckVersion rejects a volume format whose MetaVersion exceeds the MaxVersion supported by this client binary. The volume was created or upgraded by a newer JuiceFS with metadata features this client cannot read.

Source

Thrown at pkg/meta/config.go:172

	}
	if f.SessionToken != "" {
		f.SessionToken = "removed"
	}
	if f.EncryptKey != "" {
		f.EncryptKey = "removed"
	}
}

func (f *Format) String() string {
	t := *f
	t.RemoveSecret()
	s, _ := json.MarshalIndent(t, "", "  ")
	return string(s)
}

func (f *Format) CheckVersion() error {
	if f.MetaVersion > MaxVersion {
		return fmt.Errorf("incompatible metadata version: %d; please upgrade the client", f.MetaVersion)
	}

	ver := version.GetVersion()
	return f.CheckCliVersion(&ver)
}

func (f *Format) CheckCliVersion(ver *version.Semver) error {
	if ver == nil {
		return errors.New("version is nil")
	}

	if f.MinClientVersion != "" {
		minClientVer := version.Parse(f.MinClientVersion)
		r, err := version.CompareVersions(ver, minClientVer)
		if err == nil && r < 0 {
			err = fmt.Errorf("allowed minimum version: %s; please upgrade the client", f.MinClientVersion)
		}
		if err != nil {

View on GitHub (pinned to c9a67b23e8)

Solutions

Upgrade all clients to a JuiceFS release supporting the volume's meta version
Verify the volume's meta version (juicefs status) and pick a matching client version
Do not downgrade the volume's meta version manually; metadata may already use the new format

Example fix

// before
old client (MaxVersion=1) mounts volume with MetaVersion=2
// after
upgrade binary: wget newer juicefs release, replace client, remount

Defensive patterns

Strategy: validation

Validate before calling

st, err := juicefsStatus(metaURL)
if err == nil && st.MetaVersion > supportedMaxVersion {
    return fmt.Errorf("volume meta version %d needs a newer client", st.MetaVersion)
}

Try / catch

if err := format.CheckVersion(); err != nil {
    if strings.Contains(err.Error(), "incompatible metadata version") {
        // block mount; instruct operator to upgrade client
    }
    return err
}

Prevention

Keep all cluster clients on the same release train
Check volume meta version before rolling back any client
Subscribe to release notes for meta version bumps before upgrading any single client

When it happens

Trigger: Mounting/formatting against a volume whose stored Format.MetaVersion > MaxVersion; calling Format.CheckVersion() at client startup after another (newer) client upgraded the volume.

Common situations: Mixed-version cluster: an admin upgraded some clients, which bumped the volume's meta version; older client then tries to mount; volume created with a dev build then accessed by a stable release.

Related errors

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