{"record":{"id":"fb8ce7c8e28563d6","repo":"juicedata/juicefs","slug":"allowed-minimum-version-s-please-upgrade-the-cl","errorCode":null,"errorMessage":"allowed minimum version: %s; please upgrade the client","messagePattern":"allowed minimum version: (.+?); please upgrade the client","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/config.go","lineNumber":188,"sourceCode":"func (f *Format) CheckVersion() error {\n\tif f.MetaVersion > MaxVersion {\n\t\treturn fmt.Errorf(\"incompatible metadata version: %d; please upgrade the client\", f.MetaVersion)\n\t}\n\n\tver := version.GetVersion()\n\treturn f.CheckCliVersion(&ver)\n}\n\nfunc (f *Format) CheckCliVersion(ver *version.Semver) error {\n\tif ver == nil {\n\t\treturn errors.New(\"version is nil\")\n\t}\n\n\tif f.MinClientVersion != \"\" {\n\t\tminClientVer := version.Parse(f.MinClientVersion)\n\t\tr, err := version.CompareVersions(ver, minClientVer)\n\t\tif err == nil && r < 0 {\n\t\t\terr = fmt.Errorf(\"allowed minimum version: %s; please upgrade the client\", f.MinClientVersion)\n\t\t}\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\tif f.MaxClientVersion != \"\" {\n\t\tmaxClientVer := version.Parse(f.MaxClientVersion)\n\t\tr, err := version.CompareVersions(ver, maxClientVer)\n\t\tif err == nil && r > 0 {\n\t\t\terr = fmt.Errorf(\"allowed maximum version: %s; please use an older client\", f.MaxClientVersion)\n\t\t}\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/config.go#L170-L206","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nimage: juicedata/juicefs:v1.0.0  # volume requires v1.2.0\n// after\nimage: juicedata/juicefs:v1.2.0","handlingStrategy":"validation","validationCode":"ver := version.Parse(runtimeVersion)\nminVer := version.Parse(format.MinClientVersion)\nif version.CompareVersions(ver, minVer) < 0 {\n    return fmt.Errorf(\"client %s < required %s\", runtimeVersion, format.MinClientVersion)\n}","typeGuard":null,"tryCatchPattern":"if err := format.CheckCliVersion(&ver); err != nil {\n    if strings.Contains(err.Error(), \"allowed minimum version\") {\n        // upgrade path\n    }\n    return err\n}","preventionTips":["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"],"tags":["version","compatibility","client","upgrade"],"backgroundTag":"incompatible-client-version","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}