{"record":{"id":"9c07a71d526fd8a2","repo":"juicedata/juicefs","slug":"update-format-9c07a7","errorCode":null,"errorMessage":"update format","messagePattern":"update format","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/tkv.go","lineNumber":557,"sourceCode":"\t\t\t\treturn errors.Wrap(err, \"delete 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\tuserPrefix := m.fmtKey(\"QU\")\n\t\t\tgroupPrefix := m.fmtKey(\"QG\")\n\t\t\terr := m.txn(Background(), func(tx *kvTxn) error {\n\t\t\t\ttx.deleteKeys(userPrefix)\n\t\t\t\ttx.deleteKeys(groupPrefix)\n\t\t\t\tm.genLog(tx, time.Now(), \"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, \"delete user group quota\")\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\tts := time.Now().Unix()\n\tattr := &Attr{\n\t\tTyp:    TypeDirectory,\n\t\tAtime:  ts,\n\t\tMtime:  ts,\n\t\tCtime:  ts,\n\t\tNlink:  2,\n\t\tLength: 4 << 10,\n\t\tParent: RootInode,","sourceCodeStart":539,"sourceCodeEnd":575,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv.go#L539-L575","documentation":"In kvMeta.doInit (pkg/meta/tkv.go:557), after optional cleanups the new Format is reconciled with the stored one via format.update(&old, force); any validation failure (e.g. changing protected fields like Name/UUID/storage settings, or invalid capacity/inodes) is wrapped as \"update format\". This is the user-facing rejection when `juicefs format` tries an impermissible change on an existing volume.","triggerScenarios":"Re-running `juicefs format` against an existing volume with changed settings (e.g. different storage bucket, capacity, or secrets) without --force; or passing values the Format update validation rejects (negative capacity, conflicting flags).","commonSituations":"Operators attempting to move object storage or shrink capacity in place; typo'd flags re-applying a format; automation replaying a format manifest differing from the live volume; forgetting --force for allowed updates.","solutions":["Read the wrapped cause: only fields allowed by Format.update can change; revert unintended flags to match the existing volume.","If the change is intentionally permitted (e.g. updating secrets/capacity), re-run with `--force`.","To change immutable fields (storage backend, name), create a new volume and migrate data with `juicefs sync` instead of re-formatting."],"exampleFix":"// before\njuicefs format redis://host:6379/1 jfs --storage s3 --bucket s3://new-bucket\n// after\njuicefs format redis://host:6379/1 jfs --capacity 1024 --force  # only permitted fields, explicit confirmation","handlingStrategy":"validation","validationCode":"// diff intended format against the live one before formatting\nold, _ := loadFormat(metaURL)\nif old.Storage != newFormat.Storage || old.Bucket != newFormat.Bucket {\n    return errors.New(\"storage/bucket is immutable; create a new volume and sync data\")\n}","typeGuard":null,"tryCatchPattern":"if err := formatVolume(); err != nil {\n    if strings.Contains(err.Error(), \"update format\") {\n        // revert disallowed flags or re-run with --force for permitted changes\n    }\n}","preventionTips":["Read `juicefs status <meta-url>` first and only change fields permitted by Format.update.","Use --force deliberately and only for allowed in-place updates (e.g. capacity, secrets).","To move storage backends, create a new volume and migrate with `juicefs sync` instead of re-formatting."],"tags":["go","kv","format","validation","cli"],"backgroundTag":"invalid-config-value","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"}