What causes "insert/update failed" in juicedata/juicefs?

Retry the flock operation; transient races between competing lockers are the usual cause.

insert/update failed

Error message

insert/update failed

What it means

When a client tries to acquire (or convert) a POSIX flock, sql_lock.go inserts a new `flock` row or updates an existing one; the write is expected to affect exactly 1 row. If xorm reports 0 affected rows despite no SQL error, JuiceFS raises this error because the lock state was not persisted and the flock cannot be considered held.

Source

Thrown at pkg/meta/sql_lock.go:91

						return syscall.EAGAIN
					}
				}
				typec = 'R'
			} else if len(locks) > 0 {
				return syscall.EAGAIN
			}
			var n int64
			if ok {
				if flk.Ltype != typec {
					n, err = s.MustCols("inode", "owner", "sid").Cols("Ltype").Update(&flock{Ltype: typec}, &flock{Inode: inode, Owner: owner, Sid: m.sid})
				} else {
					n = 1
				}
			} else {
				n, err = s.InsertOne(&flock{Inode: inode, Owner: owner, Ltype: typec, Sid: m.sid})
			}
			if err == nil && n == 0 {
				err = fmt.Errorf("insert/update failed")
			}
			if err == nil {
				m.genLog(ctx, s, time.Now().UnixNano(), "FLOCK(%d,%d,%c)", inode, owner_, typec)
			}
			return err
		}, inode))

		if !block || err != syscall.EAGAIN {
			break
		}
		if ltype == F_WRLCK {
			time.Sleep(time.Millisecond * 1)
		} else {
			time.Sleep(time.Millisecond * 10)
		}
		if ctx.Canceled() {
			return syscall.EINTR
		}

View on GitHub (pinned to c9a67b23e8)

Solutions

Retry the flock operation; transient races between competing lockers are the usual cause.
Check for stale sessions (`juicefs status <meta-url>`) and ensure old clients exited cleanly; clear dead sessions with `juicefs destroy` if needed.
Inspect database connectivity/latency — slow transactions widen the race window; tune the DB or reduce clients.
Upgrade JuiceFS if on an older version; lock handling in sql_lock.go has been hardened over time.

Defensive patterns

Strategy: retry

Try / catch

for i := 0; i < 3; i++ {
    if err := flock(fd, LOCK_EX); err == nil { break }
    time.Sleep(backoff(i))
}

Prevention

Ensure all clients shut down cleanly so flocks are released, not timed out
Clean stale sessions before debugging lock errors (juicefs status/destroy)
Keep metadata DB latency low; contention widens race windows

When it happens

Trigger: Calling flock()/Flock (flockAc/Flock through Meta.Flock) when the `Update` matched no row and the `InsertOne` returned RowsAffected=0 — e.g. the flock row was concurrently deleted by another session releasing the lock between the update attempt and insert.

Common situations: Heavy lock contention between multiple JuiceFS clients/mounts on the same volume where the flock row is created and dropped concurrently; database connection races during client session cleanup (ClearSession removing flocks of a dying sid).

Related errors

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