quarkusio/quarkus · error · IllegalArgumentException

Unknown transaction phase

Error message

Unknown transaction phase 

What it means

ArC's EventImpl supports transactional observers (TransactionPhase.IN_PROGRESS, BEFORE_COMPLETION, AFTER_COMPLETION, AFTER_SUCCESS, AFTER_FAILURE). Internally each phase maps to a status enum; if an unknown phase value arrives, IllegalArgumentException('Unknown transaction phase ...') is thrown. This is a defensive check and normally indicates a new/unknown enum constant or corrupted wiring rather than user code error.

Source

Thrown at independent-projects/arc/runtime/src/main/java/io/quarkus/arc/impl/EventImpl.java:592

         * matches this status.
         *
         * @param status the given status code
         * @return true if the status code matches
         */
        public abstract boolean matches(int status);

        public static Status valueOf(TransactionPhase transactionPhase) {
            if (transactionPhase == TransactionPhase.BEFORE_COMPLETION
                    || transactionPhase == TransactionPhase.AFTER_COMPLETION) {
                return Status.ALL;
            }
            if (transactionPhase == TransactionPhase.AFTER_SUCCESS) {
                return Status.SUCCESS;
            }
            if (transactionPhase == TransactionPhase.AFTER_FAILURE) {
                return Status.FAILURE;
            }
            throw new IllegalArgumentException("Unknown transaction phase " + transactionPhase);
        }

    }

    /**
     * There are two different strategies of exception handling for observer methods. When an exception is raised by a
     * synchronous or transactional observer for
     * a synchronous event, this exception stops the notification chain and the exception is propagated immediately. On the
     * other hand, an exception thrown
     * during asynchronous event delivery is never propagated directly. Instead, all the exceptions for a given
     * asynchronous event are collected and then
     * made available together using CompletionException.
     *
     * @author Jozef Hartinger
     *
     */
    protected interface ObserverExceptionHandler {

View on GitHub (pinned to e1c734241f)

Solutions

1. Upgrade or align the Quarkus/ArC version so EventImpl and TransactionPhase come from the same release
2. Check that no dependency provides a conflicting javax/jakarta.transaction.TransactionPhase on the classpath
3. If implementing custom event machinery, handle all TransactionPhase constants in your mapping

// Only valid phases
Set<TransactionPhase> VALID = Set.of(TransactionPhase.IN_PROGRESS, TransactionPhase.BEFORE_COMPLETION,
    TransactionPhase.AFTER_COMPLETION, TransactionPhase.AFTER_SUCCESS, TransactionPhase.AFTER_FAILURE);
if (!VALID.contains(phase)) throw new IllegalArgumentException("Unsupported phase: " + phase);

try {
    new EventImpl<>(type, qualifiers, ip, phase, ...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown transaction phase")) {
        throw new IllegalStateException("TransactionPhase mapping out of sync with ArC runtime", e);
    }
    throw e;
}

When it happens

Trigger: Constructing an EventImpl (or using the event transaction-phase mapping code path) with a TransactionPhase value not handled by the switch — practically only when a TransactionPhase constant is added upstream without updating this mapping, or a custom/foreign TransactionPhase enum is passed programmatically.

Common situations: Version mismatch between the ArC runtime and code compiled against a newer jakarta.transaction/CDI TransactionPhase; custom event implementations forwarding an unsupported phase.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Event injection point can never be raw type - please specify
• Synthetic observer declared as asynchronous and transactiona
• Event#select(TypeLiteral, Annotation...) cannot be used with
• CDI event payload cannot contain unresolved type variable; f
• Quarkus does not support CDI Full @Specializes annotation; t

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/bd9b576501b52e30. Report an issue: GitHub.