What causes "allowed minimum version: %s; please upgrade the client" in juicedata/juicefs?

Upgrade the client to at least the version shown in the message, then remount

allowed minimum version: %s; please upgrade the client

Error message

allowed minimum version: %s; please upgrade the client

What it means

CheckCliVersion rejects the running client because its version is below the volume's configured MinClientVersion. Volume operators use this to force all clients onto a minimum release before enabling newer features.

Source

Thrown at pkg/meta/config.go:188

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 {
			return err
		}
	}
	if f.MaxClientVersion != "" {
		maxClientVer := version.Parse(f.MaxClientVersion)
		r, err := version.CompareVersions(ver, maxClientVer)
		if err == nil && r > 0 {
			err = fmt.Errorf("allowed maximum version: %s; please use an older client", f.MaxClientVersion)
		}
		if err != nil {
			return err
		}
	}
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Upgrade the client to at least the version shown in the message, then remount
Pin deployment images/Docker tags to a version >= MinClientVersion
If the minimum is too strict for your environment, have the volume admin lower MinClientVersion deliberately (only if features permit)

Example fix

// before
image: juicedata/juicefs:v1.0.0  # volume requires v1.2.0
// after
image: juicedata/juicefs:v1.2.0

Defensive patterns

Strategy: validation

Validate before calling

ver := version.Parse(runtimeVersion)
minVer := version.Parse(format.MinClientVersion)
if version.CompareVersions(ver, minVer) < 0 {
    return fmt.Errorf("client %s < required %s", runtimeVersion, format.MinClientVersion)
}

Try / catch

if err := format.CheckCliVersion(&ver); err != nil {
    if strings.Contains(err.Error(), "allowed minimum version") {
        // upgrade path
    }
    return err
}

Prevention

Pin client/container images to versions >= the volume's MinClientVersion
Check `juicefs status` MinClientVersion before deploying new nodes
Plan rolling upgrades so every node meets the minimum before enabling new features

When it happens

Trigger: Format.CheckCliVersion() comparing version.GetVersion() against f.MinClientVersion via version.CompareVersions, returning r < 0 — i.e. mounting a volume that requires, say, 1.2.0 with a 1.1.x client.

Common situations: Operator set MinClientVersion after enabling a new metadata feature; automated deployments pinned to an old image; rolling upgrades where some nodes still run stale binaries.

Related errors

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