juicedata/juicefs · critical

load setting: %s

Error message

load setting: %s

What it means

newJFS (jfs object-storage backend bootstrap) calls metaCli.Load(true) to fetch the volume's format/setting from the metadata engine; any error is wrapped as 'load setting: %s'. It means the client could not read the volume configuration from the metadata URL, so the storage cannot be set up.

Source

Thrown at cmd/object.go:518

}

func newJFS(endpoint, accessKey, secretKey, token string) (object.ObjectStorage, error) {
	pid, uid, gid = uint32(os.Getpid()), uint32(utils.GetCurrentUID()), uint32(utils.GetCurrentGID())
	if runtime.GOOS == "windows" && utils.IsWinAdminOrElevatedPrivilege() {
		uid = 0
		gid = 0
	}
	metaUrl := os.Getenv(endpoint)
	if metaUrl == "" {
		metaUrl = endpoint
	}
	metaConf := meta.DefaultConf()
	metaConf.MaxDeletes = 10
	metaConf.NoBGJob = true
	metaCli := meta.NewClient(metaUrl, metaConf)
	format, err := metaCli.Load(true)
	if err != nil {
		return nil, fmt.Errorf("load setting: %s", err)
	}
	blob, err := NewReloadableStorage(format, metaCli, nil)
	if err != nil {
		return nil, fmt.Errorf("object storage: %s", err)
	}
	chunkConf := getDefaultChunkConf(format)
	store := chunk.NewCachedStore(blob, *chunkConf, nil)
	registerMetaMsg(metaCli, store, chunkConf)
	err = metaCli.NewSession(false)
	if err != nil {
		return nil, fmt.Errorf("new session: %s", err)
	}
	metaCli.OnReload(func(fmt *meta.Format) {
		store.UpdateLimit(fmt.UploadLimit, fmt.DownloadLimit)
	})

	vfsConf := &vfs.Config{
		Meta:            metaConf,

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Verify the metadata URL and credentials, and that the engine is reachable (redis-cli/psql connect test).
2. Confirm the volume exists: run `juicefs status <meta-url>` — if not formatted, run `juicefs format` first.
3. Check firewall/network to the metadata server port.
4. Inspect the wrapped error string for the engine-specific cause (NOAUTH, connection refused, no such table, etc.).

Example fix

// before
metaUrl := "redis://wrong-host:6379/1"
// after: verify first
$ juicefs status redis://correct-host:6379/1
metaUrl := "redis://correct-host:6379/1"

// verify metadata engine reachability and volume existence first
$ juicefs status redis://host:6379/1

cli := meta.NewClient(metaUrl, metaConf)
if _, err := cli.Load(true); err != nil {
    return fmt.Errorf("load setting: %s", err)
}

When it happens

Trigger: `juicefs gateway`/`sync` with a jfs:// target where metaCli.Load fails: unreachable metadata engine (Redis/SQL/KV down), wrong metadata URL, volume not formatted (no setting record), auth failure to Redis/DB.

Common situations: Redis metadata server restarted/password changed; SQLite file path missing; metadata URL typo (redis:// vs rediss://); volume deleted but URL still referenced; network firewall blocking the metadata port.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• database %s is used by volume %s
• new session: %s
• create session: %s
• load user/group quotas: %w
• existing format is broken: %s

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