{"record":{"id":"1697f2f5997b08f3","repo":"Tencent/WeKnora","slug":"begin-sandbox-turn-lease-w","errorCode":null,"errorMessage":"begin sandbox turn lease: %w","messagePattern":"begin sandbox turn lease: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sandbox/session_binding_redis.go","lineNumber":320,"sourceCode":"\t}\n\treturn out.String()\n}\n\n// BeginTurn opens a chat-turn lease. The first increment of a session's\n// refcount allows the next resolve to rebuild a stale sandbox.\nfunc (s *RedisSessionSandboxBindingStore) BeginTurn(\n\tctx context.Context,\n\tkey SessionSandboxKey,\n) error {\n\tif err := key.Validate(); err != nil {\n\t\treturn err\n\t}\n\tttlMS := sessionTurnLeaseTTL.Milliseconds()\n\tif ttlMS <= 0 {\n\t\tttlMS = (30 * time.Minute).Milliseconds()\n\t}\n\tif err := beginTurnScript.Run(ctx, s.client, []string{s.turnKey(key)}, ttlMS).Err(); err != nil {\n\t\treturn fmt.Errorf(\"begin sandbox turn lease: %w\", err)\n\t}\n\treturn nil\n}\n\n// EndTurn releases one chat-turn lease. The last release drops the lease so\n// a later resolve may rebuild a stale sandbox immediately.\nfunc (s *RedisSessionSandboxBindingStore) EndTurn(\n\tctx context.Context,\n\tkey SessionSandboxKey,\n) error {\n\tif err := key.Validate(); err != nil {\n\t\treturn err\n\t}\n\tif err := endTurnScript.Run(ctx, s.client, []string{s.turnKey(key)}).Err(); err != nil {\n\t\treturn fmt.Errorf(\"end sandbox turn lease: %w\", err)\n\t}\n\treturn nil\n}","sourceCodeStart":302,"sourceCodeEnd":338,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/sandbox/session_binding_redis.go#L302-L338","documentation":"Returned by RedisSessionSandboxBindingStore.BeginTurn when the beginTurnScript (HINCRBY refs + PEXPIRE) fails to run — Redis unreachable, context cancelled, or server rejection. The chat-turn lease was not opened, so the caller must assume no rebuild allowance exists for the turn. Wrapped as 'begin sandbox turn lease: %w'.","triggerScenarios":"Calling BeginTurn(ctx, key) at chat-turn start when Redis is down or the ctx is already expired/cancelled; connection pool exhaustion under concurrency; server OOM or read-only replica rejecting the write.","commonSituations":"Redis restarts mid-conversation; per-request timeouts too short so ctx is nearly spent by the time the turn begins; a network partition during peak load; wrong Redis credentials after a rotation.","solutions":["Check redis-cli ping and REDIS_* env config","Ensure ctx has remaining budget when BeginTurn is called — budget a dedicated timeout for the lease step","Retry BeginTurn once; a duplicate increment is recoverable by a matching EndTurn","Inspect server logs for OOM/READONLY/NOAUTH and address the server-side condition"],"exampleFix":"// before\nif err := store.BeginTurn(ctx, key); err != nil { return err }\n// after: dedicated short-timeout context + one retry\nturnCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\nerr := store.BeginTurn(turnCtx, key)\ncancel()\nif err != nil {\n    time.Sleep(100 * time.Millisecond)\n    turnCtx, cancel2 := context.WithTimeout(context.Background(), 5*time.Second)\n    defer cancel2()\n    if rerr := store.BeginTurn(turnCtx, key); rerr != nil {\n        return fmt.Errorf(\"open turn: %w\", rerr)\n    }\n}","handlingStrategy":"retry","validationCode":"// ensure the key is valid and Redis reachable before opening the turn\nif err := key.Validate(); err != nil { return err }\nif err := rdb.Ping(ctx).Err(); err != nil {\n    return fmt.Errorf(\"cannot open turn, redis down: %w\", err)\n}","typeGuard":"func isBeginTurnError(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"begin sandbox turn lease\")\n}","tryCatchPattern":"if err := store.BeginTurn(ctx, key); err != nil {\n    if isBeginTurnError(err) {\n        // one retry with a fresh short timeout; a duplicate increment is closed by EndTurn\n        rctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)\n        defer cancel()\n        if rerr := store.BeginTurn(rctx, key); rerr != nil {\n            return fmt.Errorf(\"turn lease unavailable: %w\", rerr)\n        }\n    } else {\n        return err\n    }\n}\ndefer func() {\n    ectx, cancel := context.WithTimeout(context.Background(), 3*time.Second)\n    defer cancel()\n    _ = store.EndTurn(ectx, key)\n}()","preventionTips":["Always pair BeginTurn with a deferred EndTurn on a detached context","Do not pass a nearly-expired request context into BeginTurn — reserve a dedicated budget","Monitor Redis availability; turn open failures cluster around Redis incidents","After credential rotation, restart app instances rather than hot-swapping passwords"],"tags":["redis","lua-script","lease","go"],"backgroundTag":"redis-unreachable","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}