skills.rest
alex-quan-001
alex-quan-001COMMUNITY
Explore all skills by this author →
GitHub

transaction-oncall-handbook

Reference known TiDB/TiKV transaction incident patterns, root causes, and workarounds.

Updated Jun 3, 2026
Search Tags:#transaction#oncall#tidb#known issues#performance diagnosis#tikv#database troubleshooting
One-click install
npx skills add https://github.com/alex-quan-001/nutshell-skills --skill transaction-oncall-handbook
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: transaction-oncall-handbook
Source: https://github.com/alex-quan-001/nutshell-skills/tree/main/skills/diagnosis/transaction-oncall-handbook
Command: npx skills add https://github.com/alex-quan-001/nutshell-skills --skill transaction-oncall-handbook

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This skill eliminates the guesswork and inconsistent troubleshooting for TiDB Cloud transaction-related production incidents by providing a centralized, version-aware reference of known issues, root causes, workarounds, and fixed release information.

Core Features & Use Cases

  • Categorized Issue Library: Entries are organized by transaction subsystem (pessimistic transactions, async commit, stale/follower read, GC, pipelined DML, client-go region cache) for fast navigation to relevant incident patterns.
  • Version-Specific Guidance: Each entry documents affected TiDB/TiKV versions, fixed release lines, and related oncall tickets to match issues to your cluster's exact software version.
  • Actionable Remediation Steps: Includes root cause analysis, immediate workarounds, and fixed version references to reduce mean time to resolution for transaction correctness, latency, and availability incidents.
  • Use Case Example: When your team encounters a spike in PessimisticLockNotFound errors after enabling fair locking, use this skill to quickly identify the known bug, apply the temporary workaround to disable fair locking, and confirm the fixed version to upgrade to.

Quick Start

Use this skill to look up the known issue, root cause, workaround, and fixed version for any transaction-related incident you are investigating on your TiDB Cloud cluster.

Frequently Asked Questions about transaction-oncall-handbook

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I resolve TiDB transaction deadlocks and lock wait timeouts in production?▼

TiDB transaction deadlocks and lock wait timeouts are documented in a centralized reference with phenomenon descriptions, root cause analysis, and immediate workarounds. You can match your incident pattern to known issues across TiDB versions v5.x through v8.5+ to apply mitigation steps and identify the fixed release.

Why does my TiDB cluster experience PessimisticLockNotFound errors after enabling fair locking?▼

PessimisticLockNotFound errors after enabling fair locking are a known bug in TiDB. The transaction troubleshooting reference provides temporary workarounds like disabling fair locking and confirms the specific fixed version you should upgrade to for permanent resolution.

What is the best way to troubleshoot TiKV stale read anomalies and GC stalls?▼

The best way to troubleshoot TiKV stale read anomalies and GC stalls is to consult the centralized oncall reference organized by transaction subsystem. It provides root cause analysis, version-specific affected ranges, and actionable remediation steps to restore transaction correctness and availability.

Does this transaction troubleshooting reference cover TiDB Cloud environments running client-go region cache?▼

Yes, the reference covers client-go region cache issues alongside async commit, pipelined DML, and other transaction categories. It supports oncall engineers investigating transaction correctness, latency, and availability problems specifically within TiDB Cloud environments.

How do I find the fixed TiDB or TiKV version for a specific write conflict or transaction latency incident?▼

To find the fixed version for a write conflict or transaction latency incident, use the version-aware issue entries that document affected TiDB and TiKV releases. Each entry includes fixed release lines and related oncall ticket references to help you plan version upgrades.

What are the limitations when applying workarounds for TiDB transaction known issues?▼

Limitations include that workarounds are temporary mitigations rather than permanent fixes, requiring an upgrade to the documented fixed version for full resolution. Additionally, the reference spans versions v5.x through v8.5+, so issues outside these ranges or uncategorized transaction patterns may not be covered.

Related Skills

Explore More Software Engineering Skills→
alex-quan-001alex-quan-001

tikv-fast-tune

Diagnose TiKV performance bottleneck root causes on TiDB Cloud clusters.

Community
Advanced
alex-quan-001alex-quan-001

o11y-metrics-api

Query TiDB Cloud observability metrics via a Prometheus-compatible API.

Community
Advanced
AnastasiyaWAnastasiyaW
140

observability-monitoring

Audit Prometheus alert rules using the RED method.

Community
Advanced
alex-quan-001alex-quan-001

tikv-cdc

Diagnose TiKV and TiCDC interaction failures with curated root cause guidance.

Community
Intermediate