What causes "new session %d: %s" in juicedata/juicefs?

Read the wrapped Redis error in the message and fix its root cause (e.g., connection refused -> verify host/port; NOAUTH -> fix password via REDIS_PASSWORD or the URL).

juicedata/juicefs · error

new session %d: %s

Error message

new session %d: %s

What it means

doNewSession registers the client session in Redis (ZAdd to the session set, HSet of session info, plus a metadata log entry) inside a pipeline; if any of these Redis commands fail, the whole operation is wrapped as "new session %d: %s" (pkg/meta/redis.go:455). A failed session registration means the client cannot join the volume's session tracking, so mount/init aborts.

Source

Thrown at pkg/meta/redis.go:455

	body, err := m.rdb.Get(Background(), m.setting()).Bytes()
	if err == redis.Nil {
		return nil, nil
	}
	return body, err
}

func (m *redisMeta) doNewSession(sinfo []byte, update bool) error {
	ctx := Background()
	ssid := strconv.FormatUint(m.sid, 10)
	expire := m.expireTime()
	_, err := m.rdb.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
		pipe.ZAdd(ctx, m.allSessions(), redis.Z{Score: float64(expire), Member: ssid})
		pipe.HSet(ctx, m.sessionInfos(), ssid, sinfo)
		m.genLog(ctx, pipe, time.Now(), "NEWSESSION(%d,%d,%s)", m.sid, expire, logEncode(sinfo))
		return nil
	})
	if err != nil {
		return fmt.Errorf("new session %d: %s", m.sid, err)
	}

	if m.shaLookup, err = m.rdb.ScriptLoad(Background(), scriptLookup).Result(); err != nil {
		logger.Warnf("load scriptLookup: %v", err)
		m.shaLookup = ""
	}
	if m.shaResolve, err = m.rdb.ScriptLoad(Background(), scriptResolve).Result(); err != nil {
		logger.Warnf("load scriptResolve: %v", err)
		m.shaResolve = ""
	}

	if !m.conf.NoBGJob {
		go m.cleanupLegacies()
	}
	return nil
}

func (m *redisMeta) getCounter(name string) (int64, error) {

View on GitHub (pinned to c9a67b23e8)

Solutions

Read the wrapped Redis error in the message and fix its root cause (e.g., connection refused -> verify host/port; NOAUTH -> fix password via REDIS_PASSWORD or the URL).
Ensure you connect to the master, not a read-only replica (check with redis-cli INFO replication).
If using Redis Cluster, connect via the cluster-aware URL so MOVED redirects are handled.
Check Redis memory limits (maxmemory policy) and free memory or raise the limit.
Retry the mount after a transient failover/network blip.

Example fix

// before
juicefs mount redis://replica-host:6379/1 /mnt/jfs
// new session 1: READONLY You can't write against a read only replica.
// after: point at the master
juicefs mount redis://master-host:6379/1 /mnt/jfs

Defensive patterns

Strategy: retry

Validate before calling

// before mounting, verify the Redis endpoint accepts writes
if err := rdb.Ping(ctx).Err(); err != nil {
    return fmt.Errorf("redis not reachable: %w", err)
}
if role, _ := rdb.Do(ctx, "ROLE").String(); strings.Contains(role, "slave") {
    return errors.New("endpoint is a read-only replica; use the master")
}

Try / catch

for attempt := 0; attempt < 3; attempt++ {
    err := tryMount(redisURL)
    if err == nil || !strings.Contains(err.Error(), "new session ") {
        return err
    }
    time.Sleep(time.Duration(1<<attempt) * time.Second) // transient failover/network blip
}
return errors.New("session registration kept failing; check Redis health")

Prevention

Always point clients at the Redis master, never a read-only replica.
Monitor Redis maxmemory and set an eviction/appropriate policy.
Use the cluster-aware URL scheme for Redis Cluster so redirects are followed.
Ensure the password is set (REDIS_PASSWORD or URL) to avoid NOAUTH at startup.

When it happens

Trigger: Any Redis failure during the session-registration pipeline: connection refused/timeout, READONLY replica (writes not allowed), OOM/NOAUTH/CLUSTERDOWN errors, cluster MOVED errors, or a failover in progress when a client starts up.

Common situations: Pointing the client at a read-only replica instead of the master; Redis cluster failover or resharding during mount; Redis maxmemory reached; wrong password (NOAUTH); transient network partition between client and Redis.

Related errors

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