{"record":{"id":"98e380c0bdd3e449","repo":"juicedata/juicefs","slug":"update-format-98e380","errorCode":null,"errorMessage":"update format","messagePattern":"update format","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/sql.go","lineNumber":664,"sourceCode":"\t\t\t\treturn errors.Wrap(err, \"drop table dirStats\")\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\terr = m.txn(func(s *xorm.Session) error {\n\t\t\t\t_, err := s.Where(\"TRUE\").Delete(new(userGroupQuota))\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tm.genLog(Background(), s, time.Now().UnixNano(), \"INIT_ENABLE_USERGROUPQUOTA()\")\n\t\t\t\treturn nil\n\t\t\t})\n\t\t\tif err != nil {\n\t\t\t\treturn errors.Wrap(err, \"drop table userGroupQuota\")\n\t\t\t}\n\t\t}\n\t\tif err = format.update(&old, force); err != nil {\n\t\t\treturn errors.Wrap(err, \"update format\")\n\t\t}\n\t}\n\n\tdata, err := json.MarshalIndent(format, \"\", \"\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"json: %s\", err)\n\t}\n\n\tm.setFormat(format)\n\tn := &node{\n\t\tType:   TypeDirectory,\n\t\tNlink:  2,\n\t\tLength: 4 << 10,\n\t\tParent: RootInode,\n\t}\n\tnow := time.Now().UnixNano()\n\tn.setAtime(now)\n\tn.setMtime(now)","sourceCodeStart":646,"sourceCodeEnd":682,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/sql.go#L646-L682","documentation":"At the end of doInit for SQL metadata, `format.update(&old, force)` validates the new format against the stored one (e.g. name/UUID changes, secret key mismatch, incompatible settings). If validation fails, the error is wrapped as \"update format\" and `juicefs format` aborts without changing the volume.","triggerScenarios":"Running `juicefs format` against an existing volume with a changed name, mismatched secret key (without --force), or format fields that cannot be updated; also reached after the dirStats/userGroupQuota cleanup steps above.","commonSituations":"Typo in volume name or secret key when reformatting; trying to change immutable fields; using `juicefs format` where `juicefs config` should be used; scripting a format step against an already-initialized volume.","solutions":["Read the wrapped cause: if it is a secret key mismatch, provide the original secret key","Use `juicefs config <meta-url> --secret-key ...` or `--force` intentionally to change settings instead of re-formatting","Do not change the volume name on an existing metadata URL","If the volume is new/unwanted, drop the metadata tables or use a fresh metadata URL"],"exampleFix":"// before\njuicefs format sqlite3://test.db myjfs2   # name mismatch\n// after\njuicefs format sqlite3://test.db myjfs    # keep the original volume name","handlingStrategy":"validation","validationCode":"// compare intended format against stored one first\nstored, _ := juicefsStatus(metaURL)\nif stored.Name != newName || stored.SecretKey != newSecret { /* fix before formatting */ }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"update format\") {\n    // use the wrapped cause: name/secret mismatch => supply original values or use `juicefs config`\n}","preventionTips":["Never change the volume name on an existing metadata URL","Keep the secret key in config management and pass it identically on reformat","Prefer `juicefs config` over `juicefs format` for settings changes"],"tags":["format","validation","metadata"],"backgroundTag":"schema-validation-failed","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"}