{"record":{"id":"488f4774d613ecb5","repo":"flowable/flowable-engine","slug":"failed-to-acquire-lock-due-to-unknown-exception","errorCode":null,"errorMessage":"Failed to acquire lock {} due to unknown exception","messagePattern":"Failed to acquire lock (.+?) due to unknown exception","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/lock/LockManagerImpl.java","lineNumber":111,"sourceCode":"\n    @Override\n    public boolean acquireLock(Duration lockForceAcquireAfter) {\n        if (hasAcquiredLock) {\n            return true;\n        }\n\n        try {\n            hasAcquiredLock = executeCommand(new LockCmd(lockName, lockForceAcquireAfter, engineType));\n            if (hasAcquiredLock) {\n                LOGGER.debug(\"Successfully acquired lock {}\", lockName);\n            }\n        } catch (FlowableOptimisticLockingException ex) {\n            LOGGER.debug(\"Failed to acquire lock {} due to optimistic locking\", lockName, ex);\n            hasAcquiredLock = false;\n        } catch (FlowableException ex) {\n            if (ex.getClass().equals(FlowableException.class)) {\n                // If it is a FlowableException then log a warning and wait to try again\n                LOGGER.warn(\"Failed to acquire lock {} due to unknown exception\", lockName, ex);\n                hasAcquiredLock = false;\n            } else {\n                // Re-throw any other Flowable specific exception\n                throw ex;\n            }\n        } catch (RuntimeException ex) {\n            if (ex.getCause() instanceof SQLIntegrityConstraintViolationException) {\n                // This can happen if 2 nodes try to acquire a lock in the exact same time\n                LOGGER.debug(\"Failed to acquire lock {} due to constraint violation\", lockName, ex);\n            } else {\n                LOGGER.info(\"Failed to acquire lock {} due to unknown exception\", lockName, ex);\n            }\n            hasAcquiredLock = false;\n        }\n        return hasAcquiredLock;\n    }\n\n    @Override","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/lock/LockManagerImpl.java#L93-L129","documentation":"LockManagerImpl.acquireLock retries acquiring a named lock (typically a DB row with optimistic locking). A generic FlowableException (exactly FlowableException, not a subclass) is treated as a transient failure: it is logged as a warning and the lock acquisition is retried after a wait. The error indicates the underlying lock acquisition failed for a non-optimistic-lock reason.","triggerScenarios":"commandExecutor executing the acquire-lock logic throws a plain FlowableException from a lower layer (e.g. job/lock table access problem) while looping in acquireLock.","commonSituations":"Database connectivity hiccups or lock-contention during async executor startup; multiple cluster nodes contending for the same lock (e.g. async history or global acquire lock); schema issues in ACT_GE_PROPERTY/lock tables.","solutions":["Read the wrapped exception in the WARN log to identify the real underlying DB/engine failure and fix that first","If it's transient contention, nothing to fix — the manager retries; verify lockName and check cluster node count versus lock timeout","If persistent, verify the lock table exists and the DB user has read/write permission on it","Check the configured lock wait/retry (defaultLockTime / retry settings) and increase if contention is expected"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// acquireLock already retries internally; catch only terminal failures\ntry {\n    lockManager.acquireLock(lockName, lockOwner);\n} catch (FlowableOptimisticLockingException | FlowableInterruptedException e) {\n    // non-retryable: abort or reschedule\n    log.warn(\"lock permanently unavailable: {}\", lockName, e);\n}","preventionTips":["Keep lock retention/wait high enough for cluster contention","Verify DB connectivity and lock-table permissions before startup","Monitor WARN logs for repeated unknown exceptions — they indicate a persistent non-transient cause","Avoid many nodes acquiring the same lock at the exact same instant (stagger startup)"],"tags":["flowable","lock","retry","database","concurrency"],"backgroundTag":"database-write-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}