{"record":{"id":"5206ea6c753b4fbc","repo":"juicedata/juicefs","slug":"database-is-not-formatted-please-run-juicefs-for","errorCode":null,"errorMessage":"database is not formatted, please run `juicefs format ...` first","messagePattern":"database is not formatted, please run `juicefs format \\.\\.\\.` first","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/base.go","lineNumber":716,"sourceCode":"\tr.msgCallbacks.Lock()\n\tdefer r.msgCallbacks.Unlock()\n\tr.msgCallbacks.callbacks[mtype] = cb\n}\n\nfunc (r *baseMeta) newMsg(mid uint32, args ...interface{}) error {\n\tr.msgCallbacks.Lock()\n\tcb, ok := r.msgCallbacks.callbacks[mid]\n\tr.msgCallbacks.Unlock()\n\tif ok {\n\t\treturn cb(args...)\n\t}\n\treturn fmt.Errorf(\"message %d is not supported\", mid)\n}\n\nfunc (m *baseMeta) Load(checkVersion bool) (*Format, error) {\n\tbody, err := m.en.doLoad()\n\tif err == nil && len(body) == 0 {\n\t\terr = fmt.Errorf(\"database is not formatted, please run `juicefs format ...` first\")\n\t}\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tvar format = new(Format)\n\tif err = json.Unmarshal(body, format); err != nil {\n\t\treturn nil, fmt.Errorf(\"json: %s\", err)\n\t}\n\tif checkVersion {\n\t\tif err = format.CheckVersion(); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"check version: %s\", err)\n\t\t}\n\t}\n\tif format.Tiers == nil {\n\t\tformat.Tiers = object.NewTiers(format.StorageClass)\n\t}\n\tm.setFormat(format)\n\treturn format, nil","sourceCodeStart":698,"sourceCodeEnd":734,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/base.go#L698-L734","documentation":"baseMeta.Load reads the volume format record from the metadata engine; if doLoad returns successfully but with an empty body, the metadata database has no format record and this error is thrown. It tells the user the volume was never formatted.","triggerScenarios":"Mounting, warming up, or running any command against a metadata URL whose database exists but was never `juicefs format`-ed; pointing at an empty Redis DB or a fresh SQLite file.","commonSituations":"Typos in the metadata URL connecting to the wrong/empty Redis database index; recreating a container/volume that lost its format record; automation that creates the DB but skips the format step.","solutions":["Run `juicefs format <meta-url> <name> ...` to initialize the volume","Verify the metadata URL points to the intended database (check Redis DB index / SQLite file path)","Restore the format record from a backup (juicefs load) if it was lost"],"exampleFix":"// before: mounting an unformatted db\njuicefs mount sqlite3://test.db /tmp/jfs\n// after: format first\njuicefs format sqlite3://test.db myjfs\njuicefs mount sqlite3://test.db /tmp/jfs","handlingStrategy":"validation","validationCode":"// before mounting, verify the volume is formatted:\n// juicefs status <meta-url>  -> must return the format JSON\nfmt.Println(\"run: juicefs format <meta-url> <name> before mounting\")","typeGuard":null,"tryCatchPattern":"if _, err := meta.Load(true); err != nil { if strings.Contains(err.Error(), \"not formatted\") { return runFormat(metaURL) } return err }","preventionTips":["Always run `juicefs format` immediately after creating a new database","Double-check metadata URLs (Redis DB index, SQLite path) in configs","Keep backups (juicefs dump) so a lost format record can be restored"],"tags":["metadata","formatting","config"],"backgroundTag":"missing-required-config","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"}