juicedata/juicefs · error

new session: %s

Error message

new session: %s

What it means

This error wraps the failure of metaCli.NewSession(false) when registering a JuiceFS volume as an object storage backend ('jfs' scheme) in the S3 gateway/sync path. A metadata session is the client's registered, heartbeat-maintained connection to the metadata engine (Redis/SQL/KV); NewSession fails when the engine is unreachable, credentials are wrong, the volume was formatted with a different secret, or the client version is too old for the engine. The underlying engine error is appended to the message, so read the '%s' suffix for the real cause.

Source

Thrown at cmd/object.go:529

	}
	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,
		Format:          *format,
		Version:         version.Version(),
		Chunk:           chunkConf,
		AttrTimeout:     time.Second,
		DirEntryTimeout: time.Second,
		Mountpoint:      cliCtx.String("mountpoint"),
	}

	vfsConf.Format.RemoveSecret()
	d, _ := json.MarshalIndent(vfsConf, "  ", "")
	logger.Debugf("Config: %s", string(d))

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Read the wrapped '%s' suffix for the underlying engine error and fix that cause (connectivity, credentials, URL).
2. Verify the metadata URL is reachable, e.g. redis-cli ping or connecting to the DB with the same credentials.
3. Re-check the volume still exists: ./juicefs status <meta-url>.
4. If auth/token related, supply the correct token or remove the password from the URL after rotation.
5. Upgrade the JuiceFS client if the engine requires a newer MinClientVersion.

Example fix

// before: failing because the metadata engine is unreachable
juicefs sync jfs://myjfs/ s3://backup/   // new session: dial tcp 10.0.0.5:6379: connect: connection refused
// after: ensure the engine is up and the URL is correct
./juicefs status redis://10.0.0.5:6379/1  # verify first, then rerun sync

// before using a jfs:// object storage URL, verify the engine is reachable
if err := exec.Command("juicefs", "status", metaURL).Run(); err != nil {
    return fmt.Errorf("metadata engine not reachable for %s: %w", metaURL, err)
}

_, err := object.CreateStorage("jfs", "myjfs", "", "")
if err != nil {
    if strings.Contains(err.Error(), "new session:") {
        // inspect wrapped cause, check engine connectivity/credentials, optionally retry
    }
    return err
}

When it happens

Trigger: Calling object storage APIs against a jfs:// URL (e.g. juicefs sync or gateway with jfs source), which invokes newJFS; metaCli.NewSession returns an error because the metadata URL is bad, the engine is down, authentication fails (wrong --token / password), the volume was deleted, or MinClientVersion checks reject the client.

Common situations: Metadata engine (Redis/MySQL/TiKV) not running or network blocked; wrong metadata URL or password after a rotation; volume deleted while a job still references it; older JuiceFS binary talking to a volume created by a newer version; token mismatch for a token-protected volume.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• corrupted session info; json error: %s
• database %s is used by volume %s
• load setting: %s
• Initialize: %s
• get session ID: %s

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