juicedata/juicefs · error

database is not formatted, please run `juicefs format ...`…

Error message

database is not formatted, please run `juicefs format ...` first

What it means

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.

Solutions

1. Run `juicefs format <meta-url> <name> ...` to initialize the volume
2. Verify the metadata URL points to the intended database (check Redis DB index / SQLite file path)
3. Restore the format record from a backup (juicefs load) if it was lost

Example fix

// before: mounting an unformatted db
juicefs mount sqlite3://test.db /tmp/jfs
// after: format first
juicefs format sqlite3://test.db myjfs
juicefs mount sqlite3://test.db /tmp/jfs

// before mounting, verify the volume is formatted:
// juicefs status <meta-url>  -> must return the format JSON
fmt.Println("run: juicefs format <meta-url> <name> before mounting")

if _, err := meta.Load(true); err != nil { if strings.Contains(err.Error(), "not formatted") { return runFormat(metaURL) } return err }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• load setting
• update format
• 2. ALL entries in the metadata engine
• build tls config from
• can not generate different endpoint using

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/5206ea6c753b4fbc. Report an issue: GitHub.

Appendix: source

Thrown at pkg/meta/base.go:716

	r.msgCallbacks.Lock()
	defer r.msgCallbacks.Unlock()
	r.msgCallbacks.callbacks[mtype] = cb
}

func (r *baseMeta) newMsg(mid uint32, args ...interface{}) error {
	r.msgCallbacks.Lock()
	cb, ok := r.msgCallbacks.callbacks[mid]
	r.msgCallbacks.Unlock()
	if ok {
		return cb(args...)
	}
	return fmt.Errorf("message %d is not supported", mid)
}

func (m *baseMeta) Load(checkVersion bool) (*Format, error) {
	body, err := m.en.doLoad()
	if err == nil && len(body) == 0 {
		err = fmt.Errorf("database is not formatted, please run `juicefs format ...` first")
	}
	if err != nil {
		return nil, err
	}
	var format = new(Format)
	if err = json.Unmarshal(body, format); err != nil {
		return nil, fmt.Errorf("json: %s", err)
	}
	if checkVersion {
		if err = format.CheckVersion(); err != nil {
			return nil, fmt.Errorf("check version: %s", err)
		}
	}
	if format.Tiers == nil {
		format.Tiers = object.NewTiers(format.StorageClass)
	}
	m.setFormat(format)
	return format, nil

View on GitHub (pinned to c9a67b23e8)