{"record":{"id":"5b1c444da46520f9","repo":"juicedata/juicefs","slug":"incompatible-metadata-version-d-please-upgrade","errorCode":null,"errorMessage":"incompatible metadata version: %d; please upgrade the client","messagePattern":"incompatible metadata version: (.+?); please upgrade the client","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/config.go","lineNumber":172,"sourceCode":"\t}\n\tif f.SessionToken != \"\" {\n\t\tf.SessionToken = \"removed\"\n\t}\n\tif f.EncryptKey != \"\" {\n\t\tf.EncryptKey = \"removed\"\n\t}\n}\n\nfunc (f *Format) String() string {\n\tt := *f\n\tt.RemoveSecret()\n\ts, _ := json.MarshalIndent(t, \"\", \"  \")\n\treturn string(s)\n}\n\nfunc (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 {","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/config.go#L154-L190","documentation":"CheckVersion rejects a volume format whose MetaVersion exceeds the MaxVersion supported by this client binary. The volume was created or upgraded by a newer JuiceFS with metadata features this client cannot read.","triggerScenarios":"Mounting/formatting against a volume whose stored Format.MetaVersion > MaxVersion; calling Format.CheckVersion() at client startup after another (newer) client upgraded the volume.","commonSituations":"Mixed-version cluster: an admin upgraded some clients, which bumped the volume's meta version; older client then tries to mount; volume created with a dev build then accessed by a stable release.","solutions":["Upgrade all clients to a JuiceFS release supporting the volume's meta version","Verify the volume's meta version (juicefs status) and pick a matching client version","Do not downgrade the volume's meta version manually; metadata may already use the new format"],"exampleFix":"// before\nold client (MaxVersion=1) mounts volume with MetaVersion=2\n// after\nupgrade binary: wget newer juicefs release, replace client, remount","handlingStrategy":"validation","validationCode":"st, err := juicefsStatus(metaURL)\nif err == nil && st.MetaVersion > supportedMaxVersion {\n    return fmt.Errorf(\"volume meta version %d needs a newer client\", st.MetaVersion)\n}","typeGuard":null,"tryCatchPattern":"if err := format.CheckVersion(); err != nil {\n    if strings.Contains(err.Error(), \"incompatible metadata version\") {\n        // block mount; instruct operator to upgrade client\n    }\n    return err\n}","preventionTips":["Keep all cluster clients on the same release train","Check volume meta version before rolling back any client","Subscribe to release notes for meta version bumps before upgrading any single client"],"tags":["version","compatibility","metadata","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-14T05:17:10.506Z"}