juicedata/juicefs · critical
failed to begin transaction
Error message
failed to begin transaction
What it means
tikvClient.simpleTxn (pkg/meta/tkv_tikv.go:338) wraps a failure of client.Begin() — starting a TiKV point-get transaction pinned to MaxUint64 startTS (latest committed data, no PD access) — as "failed to begin transaction". It means the TiKV client could not even create the read transaction for a simple lookup.
Source
Thrown at pkg/meta/tkv_tikv.go:338
return strings.Contains(err.Error(), "write conflict") || strings.Contains(err.Error(), "TxnLockNotFound")
}
func (c *tikvClient) config(key string) interface{} {
if key == "startTS" {
ts, err := c.client.CurrentTimestamp(oracle.GlobalTxnScope)
if err != nil {
logger.Warnf("TiKV get startTS: %s", err)
return nil
}
return ts
}
return nil
}
func (c *tikvClient) simpleTxn(ctx context.Context, f func(*kvTxn) error, retry int) (err error) {
tx, err := c.client.Begin(tikv.WithStartTS(math.MaxUint64)) // math.MaxUint64 means to point get the latest committed data without PD access
if err != nil {
return errors.Wrap(err, "failed to begin transaction")
}
defer func() {
if r := recover(); r != nil {
if e, ok := r.(error); ok {
err = e
} else {
err = errors.Errorf("panic in point get transaction: %v", r)
}
}
}()
if err = f(&kvTxn{&tikvTxn{tx}, retry}); err != nil {
return err
}
if !tx.IsReadOnly() {
return syscall.EINVAL
}
return nil
}View on GitHub (pinned to c9a67b23e8)
Solutions
- Check the wrapped cause and verify TiKV/PD connectivity: pd-uc tctl/cluster status, and confirm the pd address in the JuiceFS meta URL is correct.
- If TLS is enabled on TiKV, ensure the client's CA/cert/key config matches; otherwise disable mismatched security settings.
- Wait out cluster maintenance (rolling restarts) and retry; JuiceFS retries internally, but persistent failure means the cluster is unreachable.
- Confirm the TiKV client version matches the server cluster (unsupportedpd/tikv version mismatch can fail Begin).
Defensive patterns
Strategy: retry
Validate before calling
// pre-flight connectivity check to PD before mounting
conn, err := net.DialTimeout("tcp", pdAddr, 3*time.Second)
if err != nil { return fmt.Errorf("PD %s unreachable: %w", pdAddr, err) }
conn.Close() Try / catch
if err := mountTiKV(); err != nil {
if strings.Contains(err.Error(), "failed to begin transaction") {
// check PD/TiKV availability and TLS config, then retry mount
}
} Prevention
- Monitor PD/TiKV endpoint reachability and set up alerts before client operations.
- Match TLS certificates between client config and the TiKV cluster.
- Schedule mounts/dumps outside cluster rolling-restart windows.
When it happens
Trigger: Any simpleTxn point-get (metadata lookups like getattr/lookup) when the TiKV transaction begins: PD/KV connection unavailable, client not initialized/closed, gRPC transport errors, or security (TLS) mismatch with the cluster.
Common situations: TiKV PD endpoints unreachable or misconfigured in the mount URL; cluster rolling restart while clients are mounted; TLS certificate mismatch; firewall blocking the TiKV client port.
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
AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06).
Data as JSON: /api/errors/696f8a6f927384ef.
Report an issue: GitHub.