{"record":{"id":"b42a17d2d1da8e93","repo":"juicedata/juicefs","slug":"existing-format-is-broken-s","errorCode":null,"errorMessage":"existing format is broken: %s","messagePattern":"existing format is broken: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/redis.go","lineNumber":345,"sourceCode":"\t})\n\treturn err\n}\n\nfunc (m *redisMeta) Name() string {\n\treturn \"redis\"\n}\n\nfunc (m *redisMeta) doInit(format *Format, force bool) error {\n\tctx := Background()\n\tbody, err := m.rdb.Get(ctx, m.setting()).Bytes()\n\tif err != nil && err != redis.Nil {\n\t\treturn err\n\t}\n\tif err == nil {\n\t\tvar old Format\n\t\terr = json.Unmarshal(body, &old)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"existing format is broken: %s\", err)\n\t\t}\n\t\tif !old.DirStats && format.DirStats {\n\t\t\t// remove dir stats as they are outdated\n\t\t\t_, err := m.rdb.TxPipelined(ctx, func(pipe redis.Pipeliner) error {\n\t\t\t\tpipe.Del(ctx, m.dirUsedInodesKey(), m.dirUsedSpaceKey())\n\t\t\t\tm.genLog(ctx, pipe, time.Now(), \"INIT_ENABLE_DIRSTATS()\")\n\t\t\t\treturn nil\n\t\t\t})\n\t\t\tif err != nil {\n\t\t\t\treturn errors.Wrap(err, \"remove dir stats\")\n\t\t\t}\n\t\t}\n\t\tif !old.UserGroupQuota && format.UserGroupQuota {\n\t\t\t// remove user group quota as they are outdated\n\t\t\t_, err := m.rdb.TxPipelined(ctx, func(pipe redis.Pipeliner) error {\n\t\t\t\tpipe.Del(ctx, m.userQuotaKey(), m.userQuotaUsedSpaceKey(), m.userQuotaUsedInodesKey(),\n\t\t\t\t\tm.groupQuotaKey(), m.groupQuotaUsedSpaceKey(), m.groupQuotaUsedInodesKey())\n\t\t\t\tm.genLog(ctx, pipe, time.Now(), \"INIT_ENABLE_USERGROUPQUOTA()\")","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/redis.go#L327-L363","documentation":"During format initialization (doInit), if the settings key already exists in Redis, its stored JSON is unmarshaled into the old Format. When that JSON cannot be parsed, this error is returned (pkg/meta/redis.go:345), signaling the volume's persisted format record in Redis is corrupted or was written by an incompatible tool. JuiceFS refuses to proceed to avoid mounting with a broken/unknown volume definition.","triggerScenarios":"Running juicefs mount / juicefs format / any meta init against a Redis where the setting key contains non-JSON data: manual edits to the key, partial writes from a crashed old client, data corruption, or the key being overwritten by another application sharing the same Redis DB.","commonSituations":"Someone hand-edited the format in redis-cli; the Redis DB index collides with another app that wrote its own data at the same key; a corrupted RDB/AOF restore; an ancient or third-party client wrote a structurally different format blob.","solutions":["Inspect the stored format: redis-cli -n <db> GET setting (key name from m.formatKey()); check whether it is valid JSON.","If the volume is disposable, delete the volume with juicefs rmr / flush the DB and re-run juicefs format.","If data must be kept, restore the format JSON from a backup (juicefs dump/backup) or reconstruct it to match the original volume settings, then retry.","Ensure no other application shares the same Redis DB index; use a dedicated DB number for the volume."],"exampleFix":"// before: inspect\n$ redis-cli -n 1 GET setting\n\"{broken...\"  // not valid JSON\n// after: restore from a backup dump or re-format an empty volume\n$ juicefs dump redis://127.0.0.1:6379/1 meta.json\n$ redis-cli -n 1 DEL setting\n$ juicefs format redis://127.0.0.1:6379/1 myjfs","handlingStrategy":"validation","validationCode":"// verify the stored format parses before initializing\nval, _ := rdb.Get(ctx, \"setting\").Result()\nvar f juicefsFormat\nif err := json.Unmarshal([]byte(val), &f); err != nil {\n    return fmt.Errorf(\"volume format in Redis is corrupted: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := juicefs.NewMeta(\"redis://...\"); err != nil {\n    if strings.Contains(err.Error(), \"existing format is broken\") {\n        // do NOT proceed; restore from juicefs dump backup or re-format an empty volume\n    }\n    return err\n}","preventionTips":["Never hand-edit the format key in Redis with redis-cli.","Give JuiceFS a dedicated Redis DB index so no other app overwrites its keys.","Keep regular juicefs dump backups so the format can be restored.","Avoid killing clients mid-format; re-format cleanly if interrupted."],"tags":["redis","metadata","json-unmarshal","corruption"],"backgroundTag":"json-unmarshal-failed","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"}