{"record":{"id":"1d8d6199c691c520","repo":"juicedata/juicefs","slug":"allowed-maximum-version-s-please-use-an-older-c","errorCode":null,"errorMessage":"allowed maximum version: %s; please use an older client","messagePattern":"allowed maximum version: (.+?); please use an older client","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/config.go","lineNumber":198,"sourceCode":"\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\nfunc newCipher(algo string, key string) (cipher.AEAD, error) {\n\tswitch algo {\n\tcase object.SM4GCM:\n\t\tblock, err := sm4.NewCipher(sm3.Kdf([]byte(key), 16))\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"new sm4 cipher: %s\", err)\n\t\t}\n\t\taead, err := cipher.NewGCM(block)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"new sm4 GCM: %s\", err)","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/config.go#L180-L216","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nimage: juicedata/juicefs:latest  # volume allows max v1.1.5\n// after\nimage: juicedata/juicefs:v1.1.5","handlingStrategy":"validation","validationCode":"ver := version.Parse(runtimeVersion)\nmaxVer := version.Parse(format.MaxClientVersion)\nif version.CompareVersions(ver, maxVer) > 0 {\n    return fmt.Errorf(\"client %s > allowed max %s\", runtimeVersion, format.MaxClientVersion)\n}","typeGuard":null,"tryCatchPattern":"if err := format.CheckCliVersion(&ver); err != nil {\n    if strings.Contains(err.Error(), \"allowed maximum version\") {\n        // use pinned older client\n    }\n    return err\n}","preventionTips":["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"],"tags":["version","compatibility","client","downgrade"],"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-14T05:17:10.506Z"}