apache/dolphinscheduler · error · RegistryException

Acquire the lock: error

Error message

Acquire the lock:  error

What it means

JdbcRegistryServer.acquireJdbcRegistryLock (blocking variant) delegates to JdbcRegistryLockManager and wraps any exception in a RegistryException with message 'Acquire the lock: <lockKey> error'. Any underlying failure — DB errors, interrupt, lock-conflict exceptions — surfaces as this RegistryException with the original exception as the cause.

Source

Thrown at dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-jdbc/src/main/java/org/apache/dolphinscheduler/plugin/registry/jdbc/server/JdbcRegistryServer.java:235

        return jdbcRegistryDataManager.listJdbcRegistryDataChildren(key);
    }

    @Override
    public void putJdbcRegistryData(Long clientId, String key, String value, DataType dataType) {
        jdbcRegistryDataManager.putJdbcRegistryData(clientId, key, value, dataType);
    }

    @Override
    public void deleteJdbcRegistryDataByKey(String key) {
        jdbcRegistryDataManager.deleteJdbcRegistryDataByKey(key);
    }

    @Override
    public void acquireJdbcRegistryLock(Long clientId, String lockKey) {
        try {
            jdbcRegistryLockManager.acquireJdbcRegistryLock(clientId, lockKey);
        } catch (Exception ex) {
            throw new RegistryException("Acquire the lock: " + lockKey + " error", ex);
        }
    }

    @Override
    public boolean acquireJdbcRegistryLock(Long clientId, String lockKey, long timeout) {
        try {
            return jdbcRegistryLockManager.acquireJdbcRegistryLock(clientId, lockKey, timeout);
        } catch (Exception ex) {
            throw new RegistryException("Acquire the lock: " + lockKey + " error", ex);
        }
    }

    @Override
    public void releaseJdbcRegistryLock(Long clientId, String lockKey) {
        try {
            jdbcRegistryLockManager.releaseJdbcRegistryLock(clientId, lockKey);
        } catch (Exception ex) {
            throw new RegistryException("Release the lock: " + lockKey + " error", ex);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Inspect the cause chain of the RegistryException for the root error (SQL/interrupt)
2. Verify the jdbc registry database connectivity and that its schema tables exist
3. Retry the acquire with backoff; if contention is high, use the timeout-based variant

Example fix

// before
registryClient.acquireJdbcRegistryLock(clientId, lockKey); // throws RegistryException on any failure
// after
try {
    registryClient.acquireJdbcRegistryLock(clientId, lockKey);
} catch (RegistryException e) {
    log.error("Lock acquire failed for {}: {}", lockKey, e.getCause());
    throw e;
}

try (Connection c = dataSource.getConnection()) { /* verify DB reachable before lock ops */ }

try { registryClient.acquireJdbcRegistryLock(clientId, lockKey); } catch (RegistryException e) { log.error("Lock acquire failed: {}", e.getCause()); }

When it happens

Trigger: Blocking acquireJdbcRegistryLock(clientId, lockKey) failing due to a database error inserting/selecting the lock row, thread interruption while waiting, or the lock manager throwing an internal exception.

Common situations: jdbc registry tables missing or unreachable (DB down/misconfigured), network flaps between the server and the metadata DB, deadlock/timeout contention when many nodes contend for the same lock key.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Get key: %s error
• Check key: %s exist error
• The client is not the lock owner of the lock:
• Jdbc lock count has gone negative for lock:
• Release the lock: error

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/9d81783e5ab8f79f. Report an issue: GitHub.