Surface Errors from UnitOfWork actions instead of hanging silently

[MateuszNaKodach]

Summary

UnitOfWork silently swallows Errors thrown by an invocation action and, as a result, hangs forever instead of failing. A single missing class on the classpath turned into a startup deadlock with no log line, no stack trace, and no exception anywhere — one of the hardest possible things to debug.

This PR makes the Unit of Work surface such failures (log + fail-fast) instead of hanging.

Why this matters

I personally lost several hours on this. Not because the problem was hard — once the underlying Error is in the logs, the cause is obvious and the fix takes a minute — but because nothing was logged at all. The app just hung with "connection refused," and I had to instrument the framework itself to find out an Error had been thrown and discarded.

That is exactly the kind of black hole we should protect our customers from. A missing/incompatible class on the classpath is one of the most common real-world failure modes, and it is precisely the situation where a clear log line saves hours. Right now the framework hides it. With this change the same situation produces an immediate, logged failure with the real stack trace — minutes, not hours.

The specific missing class below is incidental. It happened to be a Jackson annotation in my setup, but the framework defect applies to any Error — NoClassDefFoundError, NoSuchMethodError, ExceptionInInitializerError, LinkageError, etc. — thrown by an action. Any of these will hang a Unit of Work the same way.

How it showed up (a real, very hard-to-debug case)

My app simply would not become reachable on startup. curl to its HTTP port returned Connection refused.

The single most telling detail: the last application log line was the event processor announcing it was starting — and then nothing:

... INFO ... o.a.m.e.p.s.p.PooledStreamingEventProcessor : Starting PooledStreamingEventProcessor [Automation_WhenCreatureRecruitedThenAddToArmy_Processor].
   (… no further output. ever.)

That was it. No next processor, no Tomcat started, no Started …Application, no stack trace, no error — the log just stopped mid-startup. Concretely, there was:

• no exception in the logs,
• no APPLICATION FAILED TO START,
• Tomcat initialized with port 8080 … but never Tomcat started and never Started …Application,
• a thread dump showing the main thread simply parked:

"restartedMain" WAITING (parking)
    at java.util.concurrent.CompletableFuture$Signaller.block
    at java.util.concurrent.CompletableFuture.waitingGet
    at o.a.extension.spring.config.SpringLifecycleStartHandler.start(SpringLifecycleStartHandler.java:62)
    at o.s.context.support.DefaultLifecycleProcessor...startBeans
    ...

That stack tells you a lifecycle bean's start future never completes — but gives zero indication of why. The web server is bound in a later SmartLifecycle phase than the event processors, so a PooledStreamingEventProcessor whose start future never completes blocks the whole context from finishing startup, and the port is never bound. The only symptom the developer sees is "connection refused."

It took instrumenting the framework (logging each Unit-of-Work phase transition and the state of the invocation future) to discover that an Error had been thrown and lost. Once surfaced, the cause was obvious in seconds. That gap between "impossible to find" and "obvious once logged" is exactly what this PR closes.

My setup

• App: HeroesOfDomainDrivenDesign · 0f4742d (a DDD/event-sourcing sample on Axon 5)
• Axon Framework 5.2.0-SNAPSHOT, Axon Server 2026.0.0 (DCB), JPA TokenStore, Spring Boot 3.5.x
• A mixed Jackson 2.x / Jackson 3.x classpath: axon-conversion uses Jackson 3 (tools.jackson:jackson-databind:3.2.0), while the Jackson 2.x line (jackson-databind:2.21.2) transitively pinned jackson-annotations:2.21.
• Jackson 3.2.0 references com.fasterxml.jackson.annotation.JsonApplyView, which only exists in jackson-annotations:2.22. So at runtime, the first token-store serialization threw NoClassDefFoundError: com/fasterxml/jackson/annotation/JsonApplyView.

The dependency mismatch was my problem to fix (bump jackson-annotations to 2.22). But the framework should have failed loudly on it rather than hanging. Again — this could be any missing/incompatible class from any dependency; the framework behavior is what this PR addresses.

Root cause

The startup path is:

PooledStreamingEventProcessor.start()
  -> unitOfWork.executeWithResult(tokenStore::retrieveStorageIdentifier)
       -> JpaTokenStore serializes the config token via the (Jackson 3) converter
            -> throws NoClassDefFoundError  (an Error, not an Exception)

Inside UnitOfWork:

private <R> CompletableFuture<R> safe(Callable<CompletableFuture<R>> action) {
    try {
        ...
        return result;
    } catch (Exception e) {              // <-- only Exception
        return CompletableFuture.failedFuture(e);
    }
}

A NoClassDefFoundError is an Error, so it is not caught here. It escapes safe(...) before .whenComplete(alsoComplete(result)) is ever attached, so the result future is never completed (neither normally nor exceptionally).

Then:

public <R> CompletableFuture<R> executeWithResult(Function<...> action) {
    CompletableFuture<R> result = new CompletableFuture<>();
    onInvocation(pc -> safe(() -> action.apply(pc)).whenComplete(alsoComplete(result)));
    return execute().thenCombine(result, (executeResult, invocationResult) -> invocationResult);
}

thenCombine only fires when both execute() and result complete. execute() (the commit) does complete — exceptionally — but result never does, so the combined future hangs forever. The processor's start future never settles, and the application deadlocks during startup.

So two things conspired: (1) the Error was swallowed/lost, and (2) the future combinator waited on a future that could never complete.

The fix

1. Don't swallow Errors; log them. safe() now catches Throwable, completes the future exceptionally (so it propagates to the caller), and logs Errors loudly — because they indicate severe, easily-missed problems. Ordinary business Exceptions are intentionally not logged here (hot path; the caller already observes them via the failed future).

2. Fail fast on commit failure. executeWithResult uses thenCompose instead of thenCombine, so a failed commit propagates immediately rather than blocking on a result future that may never settle. On a successful commit the invocation phase has already run, so result is complete and its value/failure is returned as before.

Why thenCompose is the right combinator here (not just defense-in-depth)

thenCombine is meant for two independent futures running in parallel: it completes once both finish. But execute() and result are not independent — result is a byproduct of execute(). execute() (= commit()) drives the phases, and result is completed mid-way, during the INVOCATION phase, via safe(action).whenComplete(alsoComplete(result)). There is a single pipeline (the commit); nothing runs concurrently. So thenCombine here just means "wait for the later of the two (normally execute()) and yield result" — which is precisely what thenCompose(ignored -> result) expresses, but faithfully.

thenCompose preserves both original guarantees:

1. it still waits for the full commit before returning (the lambda runs only after execute() completes), and
2. it still returns the action's value (result, settled by then).

…and it is strictly more correct, because result is only ever completed inside the INVOCATION phase. So result never settles whenever that phase doesn't run to completion — and thenCombine then hangs forever. There are two such cases:

• The one in this issue: the action throws an Error, so result is orphaned. (Also addressed by fix Create 5 minute introduction to CQRS / Axon #1.)
• A second case that fix Create 5 minute introduction to CQRS / Axon #1 alone does not cover: the commit fails in an earlier phase (e.g. PRE_INVOCATION / begin-transaction throws). The INVOCATION action never runs, result is never completed, and thenCombine would deadlock again even though the error is now caught.

thenCompose short-circuits on execute()'s failure in both cases, so the Unit of Work fails fast regardless of where in the commit the failure occurs. The happy path is byte-for-byte equivalent.

Before / after

	Before	After
Error thrown by an invocation action	swallowed; result never completes	logged at ERROR; future completes exceptionally
executeWithResult future	hangs forever	fails fast with the original cause
App symptom	silent startup deadlock, "connection refused"	APPLICATION FAILED TO START with the real stack trace

Notes for reviewers

• Catching Throwable means severe Errors (e.g. OutOfMemoryError) also become failed futures rather than propagating on the executing thread. That is the intended behavior for this boundary: the action's outcome must be observable via the returned future, and an Error lost on an arbitrary worker/callback thread is strictly worse than one surfaced to the caller.
• The thenCombine → thenCompose change is behavioral only when the commit fails (it no longer blocks on a result that may never settle — including when the commit fails before the INVOCATION phase runs); the happy path is byte-for-byte unchanged. See "Why thenCompose is the right combinator here" above.
• I verified the fix against the failing app: with these changes the same dependency mismatch now produces an immediate, logged NoClassDefFoundError startup failure instead of a hang. Happy-path startup is unaffected.

[smcvb]

Good catch @MateuszNaKodach! But I got some nitty comments. Given the gravity of the Unit of Work, I'll request changes, even though they're small.

[smcvb]

My concerns have been addressed, hence I'm approving this pull request.