flowable/flowable-engine · error · UndeclaredThrowableException

TransactionCallback threw undeclared checked exception

Error message

TransactionCallback threw undeclared checked exception

What it means

Wrapper thrown by JtaTransactionInterceptor.execute: the wrapped command/callback threw a checked exception not declared by the callable signature; it is wrapped in UndeclaredThrowableException so it can propagate through the interceptor chain.

Solutions

1. Inspect the cause to find the undeclared checked exception
2. Wrap checked exceptions in FlowableException inside custom commands

When it happens

Trigger: Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/interceptor/JtaTransactionInterceptor.java:72 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/a2cb9cbffdd59e60. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/interceptor/JtaTransactionInterceptor.java:72

        Transaction oldTx = null;
        try {
            boolean existing = isExisting();
            boolean isNew = !existing || requiresNew;
            if (existing && requiresNew) {
                oldTx = doSuspend();
            }
            if (isNew) {
                doBegin();
            }
            T result;
            try {
                result = next.execute(config, command, commandExecutor);
            } catch (RuntimeException | Error ex) {
                doRollback(isNew, ex);
                throw ex;
            } catch (Exception ex) {
                doRollback(isNew, ex);
                throw new UndeclaredThrowableException(ex, "TransactionCallback threw undeclared checked exception");
            }
            if (isNew) {
                doCommit();
            }
            return result;
        } finally {
            doResume(oldTx);
        }
    }

    private void doBegin() {
        try {
            transactionManager.begin();
        } catch (NotSupportedException | SystemException e) {
            throw new TransactionException("Unable to begin transaction", e);
        }
    }

View on GitHub (pinned to d6d39ce1c6)