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

Check connectivity to the metadata database from the mounting client (host, port, credentials, max_connections).

insert new session %d: %s

Error message

insert new session %d: %s

What it means

Thrown by the SQL metadata engine (dbMeta) in NewSession when inserting the client's session row into the `jfs.session2` table fails with an error that is NOT a duplicate-entry error. The session id, a counter-based value, and the underlying database error are wrapped in the message. Duplicate sids are retried automatically; any other DB failure is fatal to session registration.

Source

Thrown at pkg/meta/sql.go:813

				if err := mustInsert(s, &beans); err != nil {
					return err
				}
				m.genLog(Background(), s, time.Now().UnixNano(), "NEWSESSION(%d,%d,%s)", m.sid, beans.Expire, logEncode(sinfo))
				return nil
			}); err == nil {
				break
			}

			if isDuplicateEntryErr(err) {
				logger.Warnf("session id %d is already used", m.sid)
				if v, e := m.incrCounter("nextSession", 1); e == nil {
					m.sid = uint64(v)
					continue
				} else {
					return fmt.Errorf("get session ID: %s", e)
				}
			} else {
				return fmt.Errorf("insert new session %d: %s", m.sid, err)
			}
		}
	}
	return nil
}

func (m *dbMeta) getSession(row interface{}, detail bool) (*Session, error) {
	var s Session
	var info []byte
	switch row := row.(type) {
	case *session2:
		s.Sid = row.Sid
		s.Expire = time.Unix(row.Expire, 0)
		info = row.Info
	case *session:
		s.Sid = row.Sid
		s.Expire = time.Unix(row.Heartbeat, 0).Add(time.Minute * 5)
		info = row.Info

View on GitHub (pinned to c9a67b23e8)

Solutions

Check connectivity to the metadata database from the mounting client (host, port, credentials, max_connections).
Read the wrapped %s detail to identify the underlying SQL error and fix it (e.g. repair missing session2 table).
Retry the mount once the database is healthy; session registration is idempotent per client.
If it recurs, verify all clients run compatible JuiceFS versions against the same metadata schema.

Example fix

// before: mount fails with "insert new session 42: driver: bad connection"
// after: ensure DB is reachable and retry
$ mysql -h dbhost -u juicefs -p -e 'SELECT 1'   # verify connectivity
$ juicefs mount mysql://juicefs@dbhost/myfs /mnt/jfs

Defensive patterns

Strategy: retry

Validate before calling

// before mounting, verify metadata DB connectivity
if err := db.Ping(); err != nil {
    return fmt.Errorf("metadata DB unreachable: %w", err)
}

Try / catch

for i := 0; i < 3; i++ {
    err := mount(metaURL, mnt)
    if err == nil || !strings.Contains(err.Error(), "insert new session") {
        break
    }
    time.Sleep(time.Duration(1<<i) * time.Second) // backoff while DB recovers
}

Prevention

Monitor metadata DB health (max_connections, wait_timeout) before mass mounts.
Keep all clients on compatible JuiceFS versions to avoid schema surprises.
Use connection pooling limits that fit the DB's capacity.

When it happens

Trigger: Mounting a JuiceFS volume backed by MySQL/PostgreSQL/SQLite where the INSERT into the session table fails: DB unreachable during mount, connection dropped mid-transaction, table missing/corrupted, transaction aborted, or lock wait timeout. Only non-duplicate errors reach this path (duplicate sid loops with a new id).

Common situations: Database restarted or network partitioned between client and metadata DB while a client mounts; max_connections exhausted on MySQL; session2 table dropped or migrated by an incompatible newer client; SQL mode / constraint conflicts after version upgrades.

Related errors

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