juicedata/juicefs · error

cannot lower min-client-version from %s to %s

Error message

cannot lower min-client-version from %s to %s

What it means

`juicefs config` refuses to lower `min-client-version`: the new value must be greater than or equal to the current one, enforced with compareVersion. Lowering could let incompatible old clients reconnect to a volume that depends on newer metadata semantics.

Source

Thrown at cmd/config.go:350

			if new := ctx.Int64(flag); new != format.ChangeLogMaxLines {
				if new < 0 {
					return fmt.Errorf("negative value for %s: %d", flag, new)
				}
				msg.WriteString(fmt.Sprintf("%10s: %d -> %d\n", flag, format.ChangeLogMaxLines, new))
				format.ChangeLogMaxLines = new
			}
		case "user-group-quota":
			if new := ctx.Bool(flag); new != format.UserGroupQuota {
				msg.WriteString(fmt.Sprintf("%10s: %t -> %t\n", flag, format.UserGroupQuota, new))
				format.UserGroupQuota = new
			}
		case "min-client-version":
			if new := ctx.String(flag); new != format.MinClientVersion {
				if version.Parse(new) == nil {
					return fmt.Errorf("Invalid version string: %s", new)
				}
				if compareVersion(new, format.MinClientVersion) < 0 {
					return fmt.Errorf("cannot lower min-client-version from %s to %s", format.MinClientVersion, new)
				}
				requireMinClientVersion(new)
			}
		case "max-client-version":
			if new := ctx.String(flag); new != format.MaxClientVersion {
				if version.Parse(new) == nil {
					return fmt.Errorf("Invalid version string: %s", new)
				}
				msg.WriteString(fmt.Sprintf("%s: %s -> %s\n", flag, format.MaxClientVersion, new))
				format.MaxClientVersion = new
				clientVer = true
			}
		case "enable-acl":
			if enableACL := ctx.Bool(flag); enableACL != format.EnableACL {
				if enableACL {
					msg.WriteString(fmt.Sprintf("%s: %v -> %v\n", flag, format.EnableACL, true))
					format.EnableACL = true
					requireMinClientVersion("1.2.0-A")

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Choose a value >= the current min-client-version (check via `juicefs config META`)
2. If lowering is truly needed, review AGENTS-doc compatibility rules and the reason the floor exists before bypassing (no supported bypass via this flag)
3. Leave the flag unset if no change is intended

Example fix

// before
juicefs config META --min-client-version 1.0.0   # current 1.2.0 -> error
// after
juicefs config META --min-client-version 1.3.0

cur=$(juicefs config META | grep min-client-version)
vercmp "$NEW" -ge "$cur" || die "cannot lower min-client-version"

When it happens

Trigger: `juicefs config META --min-client-version <lower-version>` where the requested version compares less than format.MinClientVersion.

Common situations: Rolling back an upgrade policy after setting a too-high minimum; thinking the flag sets a fixed version rather than a floor; copying a command from an older run.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Invalid version string: %s
• incompatible metadata version: %d; please upgrade the client
• allowed minimum version: %s; please upgrade the client
• allowed maximum version: %s; please use an older client
• Clients below version %s will be rejected after modification

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