Resolving SQLITE_BUSY Errors: database is locked (5)

Article Number: 000022165

Environment

SUSE Rancher v2.12.1-v2.12.5

Situation

For Rancher v2.12.1-v2.12.5, users may experience login failures and a persistent "spinning" state in the Rancher user interface (UI).

Further investigation into the logs of the rancher or cattle-cluster-agent pods will reveal recurring SQLite database contention errors similar to the following: 

2025/11/04 04:29:39 [ERROR] Error in Store.Add for type _v1_Secret: transaction: begin tx: database is locked (5) (SQLITE_BUSY)

This  SQLITE_BUSY (5) error indicates that write operations to the internal SQLite database are timing out due to excessive lock contention which causes the UI and API instability.

Cause

This issue was caused by a race condition leading to blocking, as detailed in Rancher GitHub Issue #52519.

Resolution

Temporary Workaround:

The issue can be temporarily mitigated by restarting the affected components: 

1. Restart the cattle-cluster-agent Deployment in the affected downstream cluster(s):

kubectl rollout restart deploy cattle-cluster-agent -n cattle-system

2. Restart the Rancher Deployment in the local cluster:

kubectl rollout restart deploy/rancher -n cattle-system

Permanent Fix:

Teams experiencing this issue should upgrade to one of the following versions, or higher, which include the fix:

• Rancher v2.13.1
• Rancher v2.12.6