# PD Resource Control Known Cases

Source note: adapted from the Feishu `PD oncall handbook` <https://pingcap.feishu.cn/wiki/E5KkwI6VJiFA4nkcaVEcDhWonqu>.

## Slow Read Request Caused by Lower Priority Under Resource Control

- Phenomenon:
  - Default-group read requests can become abnormally slow even when TiKV shows no obvious CPU or IO bottleneck.
- Workaround:
  - Set all resource groups to the same priority.
  - Upgrade to fixed versions.
- Fixed version:
  - `v8.5.4` / `v8.1.3` / `v7.5.8`
- Related oncall:
  - v7.5.3 slow point get `TICKET-8220`

## `Time_queued_by_rc` Can Stay High Even When Quota Appears Sufficient

- Phenomenon:
  - Request retries reacquire tokens repeatedly and accumulate queue time.
- Workaround:
  - Decrease `controller.LTBTokenRPCMaxDelay` from `1s` to `200ms`.
- Related oncall:
  - v7.5.5 high query latency despite available RU capacity `GTOC-8141`

## `controller.ltb-max-wait-duration` Config Change May Not Take Effect

- Phenomenon:
  - Changing the config through the PD config API has no effect because the controller API is the supported path.
- Workaround:
  - Set it through `pd-ctl` or `curl` against the correct controller API path.
- Related oncall:
  - v8.5.3 config modify for `controller.ltb-max-wait-duration` did not work `TCOC-4651`

## Resource Control Can Cause Latency Spikes Under Uneven TiDB Workload

- Phenomenon:
  - RU on a hot TiDB instance drops to zero while low-load TiDB instances still have equal quota.
- Workaround:
  - Keep workload balanced across TiDB instances.
- Related oncall:
  - v7.5.6 RU usage anomaly `TICKET-8004`
  - v7.5.4 RU exhaustion analysis `ONCALL-7885` / `TICKET-6290`

## Query-Limit Actions Do Not Support All Action Types Correctly

- Phenomenon:
  - Some `query_limit` actions such as `cooldown`, `switch_group`, and `dry_run` are not recognized correctly in affected versions.
- Workaround:
  - Upgrade to fixed version.
- Fixed version:
  - `v8.5.2`
- Related oncall:
  - v8.5.1 resource control `action=cooldown` observation question `TICKET-5907` / `ONCALL-7743`

## Listing Resource Groups Can Panic PD

- Phenomenon:
  - PD can panic with `json: unsupported value: NaN` while listing resource groups.
- Workaround:
  - Delete unused resource groups.
  - Or upgrade to fixed version.
- Fixed version:
  - `v7.1.4` / `v7.5.1`
- Related oncall:
  - v7.5.1 PD restarted for unknown reason `TCOC-2111`
  - v7.1.1 PD panicked in rotation `TCOC-1983`

## Resource Control Can Trigger Region-Cache Churn Without Leader Changes

- Phenomenon:
  - After enabling resource control, region-error metrics stay high even without leader scheduling.
  - Client-side region cache can be invalidated repeatedly, and requests may be sent to followers and receive `not leader`.
- Root cause:
  - `ErrClientResourceGroupThrottled` can be treated like a generic RPC failure by `client-go`, which incorrectly marks store regions as needing refill.
- Workaround:
  - Disable resource control for the workload or wait for pressure to subside.
- Related oncall:
  - v7.5.3 high `not leader` region errors in pressure testing `ONCALL-7388` / `TICKET-4943`
  - v7.1.5 TiDB server region cache invalidation caused jitter `TICKET-6012` / `ONCALL-7786`
  - v7.1.5 update write became stuck `TICKET-5641` / `ONCALL-7643`

## Users Can Hit Error 8252 Even When RU Usage Does Not Seem Exceeded

- Phenomenon:
  - SQL reports `Error 8252: Exceeded resource group quota limitation` even though observed RU usage does not appear to exceed the configured limit.
- Workaround:
  - Remove the problematic resource group if the feature is not needed.
- Related oncall:
  - v7.5.2 SQL reported error 8252 even though RU usage was not exceeded `TCOC-4498`
  - v7.5.1 TiDB resource group quota limitation error `GTOC-7084`

## Deleted Resource Groups Can Remain Visible in Metrics

- Phenomenon:
  - Deleted resource groups can remain visible on the `Available RU` panel because metrics cleanup used the wrong label set.
- Workaround:
  - Usually ignore the metrics artifact unless observability accuracy is critical.
  - Upgrade if a fixed version is available in the affected release line.
- Related oncall:
  - v8.1.0 resource-group monitoring issue `APID-10921`

## Internal SQL Can Consume Default-Group RU by Design

- Phenomenon:
  - Internal statements such as `ANALYZE` consume RU from the default group, and the workload may not appear directly in ordinary SQL views.
- Workaround:
  - No direct workaround; interpret default-group RU panels with internal SQL in mind.
- Related oncall:
  - v7.5.4 default-group RU consumption question `TCOC-2924`