{"record":{"id":"696f8a6f927384ef","repo":"juicedata/juicefs","slug":"failed-to-begin-transaction","errorCode":null,"errorMessage":"failed to begin transaction","messagePattern":"failed to begin transaction","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/tkv_tikv.go","lineNumber":338,"sourceCode":"\treturn strings.Contains(err.Error(), \"write conflict\") || strings.Contains(err.Error(), \"TxnLockNotFound\")\n}\n\nfunc (c *tikvClient) config(key string) interface{} {\n\tif key == \"startTS\" {\n\t\tts, err := c.client.CurrentTimestamp(oracle.GlobalTxnScope)\n\t\tif err != nil {\n\t\t\tlogger.Warnf(\"TiKV get startTS: %s\", err)\n\t\t\treturn nil\n\t\t}\n\t\treturn ts\n\t}\n\treturn nil\n}\n\nfunc (c *tikvClient) simpleTxn(ctx context.Context, f func(*kvTxn) error, retry int) (err error) {\n\ttx, err := c.client.Begin(tikv.WithStartTS(math.MaxUint64)) // math.MaxUint64 means to point get the latest committed data without PD access\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"failed to begin transaction\")\n\t}\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\tif e, ok := r.(error); ok {\n\t\t\t\terr = e\n\t\t\t} else {\n\t\t\t\terr = errors.Errorf(\"panic in point get transaction: %v\", r)\n\t\t\t}\n\t\t}\n\t}()\n\tif err = f(&kvTxn{&tikvTxn{tx}, retry}); err != nil {\n\t\treturn err\n\t}\n\tif !tx.IsReadOnly() {\n\t\treturn syscall.EINVAL\n\t}\n\treturn nil\n}","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv_tikv.go#L320-L356","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-flight connectivity check to PD before mounting\nconn, err := net.DialTimeout(\"tcp\", pdAddr, 3*time.Second)\nif err != nil { return fmt.Errorf(\"PD %s unreachable: %w\", pdAddr, err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"if err := mountTiKV(); err != nil {\n    if strings.Contains(err.Error(), \"failed to begin transaction\") {\n        // check PD/TiKV availability and TLS config, then retry mount\n    }\n}","preventionTips":["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."],"tags":["go","tikv","transaction","network","pd"],"backgroundTag":"connection-refused","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}