@Rocky, what config controls this timeout?

get database write lock timeout, database=some_db, timeout=300ms

The error message

get database write lock timeout

indicates that a thread (likely a loading or transaction commit process) failed to acquire the database-level write lock within the allotted time. This is typically caused by high lock contention from concurrent DDL operations (like

ALTER

,

DROP

, or

TRUNCATE

) or a massive number of concurrent write transactions. Depending on your StarRocks version, the configuration parameters that control these timeouts are: 1.

catalog_try_lock_timeout_ms

This is the most common FE configuration parameter for global and database-level lock timeouts. • Default:

5000

(5 seconds) • Description: Controls the timeout duration to obtain the global catalog lock. If your system is under heavy load or performing complex metadata operations, increasing this can help. 2.

finish_transaction_default_lock_timeout_ms

This was introduced in v3.5.8 and v4.0.0 to specifically manage the lock timeout during the transaction "finish" phase (commit or abort). • Default:

1000

(1 second) • Description: The default timeout for acquiring the database and table locks when finishing a transaction. • Note: If you are seeing a

300ms

timeout, it is possible your version has a lower internal default or this parameter has been manually tuned down. 3.

mv_refresh_try_lock_timeout_ms

If the error occurs during a Materialized View refresh: • Default:

30000

(30 seconds) • Description: The timeout for MV refresh tasks to acquire the lock on base tables. How to check and update: You can check the current values by running:

sql
ADMIN SHOW FRONTEND CONFIG LIKE '%lock_timeout%';

To increase the timeout dynamically (for mutable parameters):

sql
ADMIN SET FRONTEND CONFIG ("catalog_try_lock_timeout_ms" = "10000");

Common Causes to Investigate: * Concurrent DDL: Check if any

ALTER TABLE

,

TRUNCATE

, or

DROP

commands are running, as these hold exclusive write locks. * High Load/FE GC: If the FE is experiencing heavy JVM Garbage Collection, it may fail to process lock requests in time. Check FE logs for "Slow lock" or "Long GC" warnings. * Concurrency: If using tools like Flink, ensure your sink concurrency or flush intervals aren't overwhelming the FE's metadata lock manager. References • administration/management/FE_configuration.md

@Rocky, when this occurs, there are no DDL operations happening on the database. I can confirm that as I'm the only one using the tables in question for testing. I have many concurrent processes opening transactions to

INSERT

into the table, though. This error appears to occur when those transactions commit. Does that change your diagnosis?

Since you are seeing this error during transaction commits (

INSERT

operations) and not DDL, the diagnosis shifts to metadata lock contention in the Frontend (FE). When many concurrent transactions attempt to commit at the same time, they all compete for the database-level write lock to update metadata (like table versions). The specific configuration that controls this timeout is: 1.

finish_transaction_default_lock_timeout_ms

This is the primary configuration for the lock timeout during the transaction "finish" phase (COMMIT/ABORT). * Default:

1000

(1 second). * Availability: Introduced in v3.2.11, v3.3.3, v3.5.8, and v4.0.0. * Usage: If your StarRocks version supports it, you can increase this to allow commit threads more time to wait for the lock.

sql
    ADMIN SET FRONTEND CONFIG ("finish_transaction_default_lock_timeout_ms" = "5000");

2.

catalog_try_lock_timeout_ms

In versions where the above parameter is not available, or as a general fallback, this controls the timeout for obtaining global and database locks. * Default:

5000

(5 seconds). * Note: If you are seeing exactly

300ms

and haven't changed this, it is possible your client/connector is passing a specific timeout or your version has a lower internal default. Why is it 300ms? If you see a specific

300ms

timeout in the error message, check the following: * Connector Settings: If you are using the StarRocks Flink Connector or a custom SDK, check if there is a

label_keep_max_second

or a transaction-specific timeout property being set. Some connectors or "Stream Load" transaction APIs default to shorter internal timeouts for lock acquisition. * Session Variables: Although less common for this specific error, check if

query_timeout

or

insert_timeout

is set very low in your session. Recommendations for High-Concurrency INSERTs: Since you have many concurrent processes: 1. Increase Transaction Sharding: To reduce lock contention on the BE side (though your error is FE-side), you can increase

txn_shard_size

on the BE (default 1024, must be a power of 2). 2. Batching: Instead of many concurrent small

INSERT

transactions, try to batch more rows into a single

INSERT

statement or use

Stream Load

. This reduces the frequency of FE lock requests. 3. Check FE Health: High CPU or long JVM Garbage Collection (GC) on the FE can cause it to miss these tight 300ms lock windows. Check

fe.log

for

Slow lock

or

Long GC

messages. To verify your current settings:

sql
ADMIN SHOW FRONTEND CONFIG LIKE '%lock_timeout%';

References • administration/management/FE_configuration.md • StarRocks v3.5 Release Notes (PR #63981) References • administration/management/BE_configuration.md • administration/management/FE_configuration.md

@Rocky, what do each of these do?

+-----------------------------------------+-------+
| Variable_name                           | Value |
+-----------------------------------------+-------+
| back_pressure_throttle_time_upper_bound | 300   |
| query_delivery_timeout                  | 300   |
| query_queue_pending_timeout_second      | 300   |
| query_timeout                           | 300   |
+-----------------------------------------+-------+

I'll try setting

query_timeout

higher (as

insert_timeout

is already set quite high globally) but I just want to be sure so I'm checking everything that's set to 300.

The four variables you listed are almost all measured in seconds, meaning a value of

300

represents 5 minutes. However, the

300ms

timeout in your error message is much shorter (0.3 seconds), suggesting it is likely tied to the one variable in your list that often uses milliseconds or a specific internal lock setting. Here is the breakdown of what those four variables do: 1.

back_pressure_throttle_time_upper_bound

* Default:

300

(Milliseconds) * What it does: This controls the maximum time (in ms) a request will be "throttled" (forced to sleep) when the system detects back-pressure (e.g., when Backend memory is high or there are too many open segments). * Relation to your error: While this controls throttling, it is usually distinct from a "database write lock" timeout. However, if back-pressure is severe, it can delay transaction processing. 2.

query_timeout

* Default:

300

(Seconds) * What it does: The global/session timeout for any query or

INSERT

statement. * Note: In your case,

300

means 300 seconds (5 minutes). This is likely not the cause of a

300ms

lock timeout error. 3.

query_delivery_timeout

* Default:

300

(Seconds) * What it does: Controls how long the Frontend (FE) waits to successfully deliver plan fragments to all involved Backends (BEs). * Note: Again, this is in seconds. 4.

query_queue_pending_timeout_second

* Default:

300

(Seconds) * What it does: If you have query queues enabled, this is the maximum time a query can wait in the queue before being rejected. ────────── Why are you seeing

timeout=300ms

? If your error explicitly states

timeout=300ms

, it is likely coming from one of the following FE configurations (not session variables) that might have been tuned or defaulted to a lower value in your specific StarRocks version: 1.

catalog_try_lock_timeout_ms

: This is the FE-level config that controls how long to wait for the database/catalog lock. Its default is usually 5000ms, but if someone set it to 300, it would perfectly match your error. 2.

finish_transaction_default_lock_timeout_ms

: In newer versions (v3.2.11+, v3.5.8+), this controls the lock timeout specifically for the commit/finish phase. Check if this is set to 300. 3. Connector Configuration: If you are using a Flink/Spark connector or a specific client library, check if the client itself is passing a

300ms

timeout for the transaction commit. How to check and fix: Run this command to see the actual millisecond-level lock configurations on the Frontend:

sql
ADMIN SHOW FRONTEND CONFIG LIKE '%lock_timeout%';

If you find a parameter set to

300

, you can increase it (e.g., to 5000ms) using:

sql
ADMIN SET FRONTEND CONFIG ("catalog_try_lock_timeout_ms" = "5000");
-- OR
ADMIN SET FRONTEND CONFIG ("finish_transaction_default_lock_timeout_ms" = "5000");

Note: If you increase these and still see timeouts, the underlying issue is lock contention. Since you have many concurrent

INSERT

processes, they are all fighting for the same database write lock during the commit phase. Batching your inserts into fewer, larger transactions is the most effective way to solve this. References • administration/management/BE_configuration.md • knowledge/trouble_shooting/fe_deadlock_problems.md • administration/management/FE_configuration.md