Resolving Query Timeout Errors
The following error usually indicates that one database transaction is waiting for another transaction to release a lock on the same records:
In most cases, this is caused by application logic rather than the database itself. It typically occurs when multiple requests or background jobs attempt to modify the same document at the same time.
Why This Error Occurs
Frappe follows a transaction-based database model. Whenever your application performs database writes or executes queries using FOR UPDATE, the affected rows are locked until the transaction is either committed or rolled back.
If another request tries to access those same locked records before the first transaction completes, it must wait. When the waiting period exceeds MariaDB’s configured timeout, the database raises a Lock Wait Timeout error.
- A background job starts updating a document.
- The document remains locked while the transaction is running.
- Another web request or background job attempts to update the same document.
- The second transaction waits for the lock to be released.
- If the wait exceeds the configured timeout, a QueryTimeoutError is raised.
Common Causes
- Long-running background jobs that update many records in a single transaction.
- Multiple workers updating the same document simultaneously.
- Using
SELECT ... FOR UPDATEunnecessarily. - Transactions that perform lengthy processing before committing.
- Custom applications that do not commit or rollback transactions promptly.
How to Troubleshoot
1. Review Your Application Logic
If this error occurs repeatedly, review your custom code and identify where database locks may be held for an extended period.
Pay special attention to:
- Long-running background jobs.
- Nested database operations.
- Large batch updates.
- Custom scripts that modify the same records concurrently.
2. Understand the Transaction Model
Before debugging locking issues, it is important to understand how transactions work in Frappe. Database writes and queries executed with FOR UPDATE keep rows locked until the transaction completes.
Keeping transactions short significantly reduces the chance of lock contention.
3. Check the Site Process List
When the timeout occurs, inspect the running database processes using the Site Process List available in Frappe Cloud.
The process list helps identify:
- Currently executing SQL queries.
- Queries waiting for locks.
- Long-running transactions.
- Blocked database sessions.
Reviewing the process list while the issue is occurring often makes it possible to identify the query holding the lock.
Best Practices
- Keep database transactions as short as possible.
- Commit changes immediately after completing database updates.
- Avoid unnecessary use of
FOR UPDATE. - Split large updates into smaller batches where possible.
- Prevent multiple workers from updating the same records simultaneously.
- Monitor long-running queries using the Site Process List.
A QueryTimeoutError (1205) usually indicates that one transaction is waiting for another transaction to release a database lock. This is commonly caused by long-running transactions, concurrent updates, or unnecessary row locking. Reviewing your application’s transaction flow and inspecting the Site Process List during the error can help identify and resolve the underlying locking issue.
