Use the tools below to diagnose issues in a running TiDB cluster. The HTTP Status API, slow query log,Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pingcap/tidb/llms.txt
Use this file to discover all available pages before exploring further.
INFORMATION_SCHEMA tables, and the EXPLAIN statement are the primary diagnostic surfaces.
Slow queries
Slow queries
Identifying slow queries
TiDB writes slow queries (exceedingtidb_slow_log_threshold, default 300ms) to the slow query log and to INFORMATION_SCHEMA.SLOW_QUERY.View recent slow queries:EXPLAIN ANALYZE executes the query and returns the actual rows, loops, and time spent at each operator. Look for operators with high actRows vs estRows discrepancy — this often indicates stale statistics.Update table statistics:IndexScan or IndexLookUp in EXPLAIN output. A full TableScan on a large table is a common cause of slow queries.High memory usage
High memory usage
Diagnosing high memory usage
TiDB enforces per-query and per-instance memory limits.Check the current memory quota per query:If queries are consistently hitting the memory limit, consider adding indexes to reduce the data scanned, or increase
mem-quota-query in tidb.toml.tidb.toml:Connection issues
Connection issues
Diagnosing connection failures
TiDB accepts MySQL connections on port4000 by default.Verify TiDB is listening:| Symptom | Likely cause | Resolution |
|---|---|---|
Connection refused on port 4000 | TiDB not running or firewall | Check process and firewall rules |
Too many connections error | max-server-connections limit reached | Increase limit or add TiDB nodes |
| TLS handshake failure | Certificate mismatch or expired cert | Check ssl-ca, ssl-cert, ssl-key in config |
| Authentication failure | Wrong credentials or host restriction | Check mysql.user for allowed hosts |
tidb.toml:DDL failures
DDL failures
Diagnosing DDL failures
TiDB DDL operations run asynchronously. If a DDL job fails, inspect the job history.Check DDL job history via HTTP API:STATE column shows done, running, cancelling, or rollback done. A job in rollback done state encountered an error; check the ERROR column for details.Cancel a running DDL job:- Duplicate key violations when adding a unique index
- Insufficient disk space on TiKV nodes
- Schema version conflicts in a multi-TiDB-node setup (usually transient)
Lock contention
Lock contention
Diagnosing lock contention
TiDB uses optimistic and pessimistic transactions. Lock contention appears as slow transactions orDeadlock errors.View current lock waits:- Use pessimistic transactions (
BEGIN PESSIMISTIC) for workloads with high write contention - Keep transactions short; avoid holding locks across network round trips
- Use
SELECT ... FOR UPDATEonly where necessary - Add indexes to reduce the number of rows scanned per transaction
Reading TiDB logs
Reading TiDB logs
TiDB log locations and format
TiDB writes structured JSON logs by default. In a TiUP deployment, logs are in~/.tiup/logs/.| Field | Meaning |
|---|---|
level | info, warn, error, fatal |
msg | Human-readable message |
err | Error string if applicable |
query | SQL statement (may be truncated) |
conn | Connection ID, correlates with PROCESSLIST |
Useful INFORMATION_SCHEMA tables
| Table | Purpose |
|---|---|
INFORMATION_SCHEMA.SLOW_QUERY | Slow query log with execution plans |
INFORMATION_SCHEMA.PROCESSLIST | Active connections and running queries |
INFORMATION_SCHEMA.TIDB_TRX | Active transactions |
INFORMATION_SCHEMA.DATA_LOCK_WAITS | Current lock wait graph |
INFORMATION_SCHEMA.DEADLOCKS | Recent deadlock history |
INFORMATION_SCHEMA.CLUSTER_INFO | Topology and version of all cluster components |
INFORMATION_SCHEMA.METRICS_TABLES | Prometheus metrics queryable via SQL |