What causes "allowed maximum version: %s; please use an older client" in juicedata/juicefs?

Use a client version <= the stated maximum, then remount

allowed maximum version: %s; please use an older client

Error message

allowed maximum version: %s; please use an older client

What it means

CheckCliVersion rejects the running client because its version is greater than the volume's configured MaxClientVersion. Operators use this to prevent untested/newer clients from mounting a volume that may have behavioral changes.

Source

Thrown at pkg/meta/config.go:198

	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
}

func newCipher(algo string, key string) (cipher.AEAD, error) {
	switch algo {
	case object.SM4GCM:
		block, err := sm4.NewCipher(sm3.Kdf([]byte(key), 16))
		if err != nil {
			return nil, fmt.Errorf("new sm4 cipher: %s", err)
		}
		aead, err := cipher.NewGCM(block)
		if err != nil {
			return nil, fmt.Errorf("new sm4 GCM: %s", err)

View on GitHub (pinned to c9a67b23e8)

Solutions

Use a client version <= the stated maximum, then remount
Have the volume admin raise or clear MaxClientVersion once the newer client is validated
Separate test volumes if you need to run the newest client for evaluation

Example fix

// before
image: juicedata/juicefs:latest  # volume allows max v1.1.5
// after
image: juicedata/juicefs:v1.1.5

Defensive patterns

Strategy: validation

Validate before calling

ver := version.Parse(runtimeVersion)
maxVer := version.Parse(format.MaxClientVersion)
if version.CompareVersions(ver, maxVer) > 0 {
    return fmt.Errorf("client %s > allowed max %s", runtimeVersion, format.MaxClientVersion)
}

Try / catch

if err := format.CheckCliVersion(&ver); err != nil {
    if strings.Contains(err.Error(), "allowed maximum version") {
        // use pinned older client
    }
    return err
}

Prevention

Never deploy :latest client images against version-pinned volumes
Keep a validated client version recorded per volume
Raise MaxClientVersion only after testing the newer client on a staging volume

When it happens

Trigger: Format.CheckCliVersion() finding version.CompareVersions(ver, maxClientVer) > 0 — e.g. volume pinned to max 1.1.x being mounted by a 1.2.0 client.

Common situations: Conservative admins capping client versions to a validated release; production volumes protected against brand-new major/minor releases; CI running latest JuiceFS against a locked-down volume.

Related errors

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