quarkusio/quarkus · error · IllegalArgumentException

Unknown semantics

Error message

Unknown semantics

What it means

QuarkusTransactionImpl.call switches on the transaction semantics enum and throws IllegalArgumentException("Unknown semantics") as a catch-all if the TransactionSemantics value is not one of the handled cases (REQUIRED, REQUIRES_NEW, etc.). This indicates a semantics value the implementation does not recognize — usually a new/unknown enum constant or corrupted dispatch.

Source

Thrown at extensions/narayana-jta/runtime/src/main/java/io/quarkus/narayana/jta/QuarkusTransactionImpl.java:37

class QuarkusTransactionImpl {

    private static final Logger log = Logger.getLogger(QuarkusTransactionImpl.class);
    private static TransactionManager cachedTransactionManager;
    private static UserTransaction cachedUserTransaction;

    public static <T> T call(RunOptionsBase options, Callable<T> task) {
        switch (options.semantics) {
            case REQUIRE_NEW:
                return callRequireNew(options, task);
            case DISALLOW_EXISTING:
                return callDisallowExisting(options, task);
            case JOIN_EXISTING:
                return callJoinExisting(options, task);
            case SUSPEND_EXISTING:
                return callSuspendExisting(options, task);
        }
        throw new IllegalArgumentException("Unknown semantics");
    }

    private static <T> T callSuspendExisting(RunOptionsBase options, Callable<T> task) {
        if (options.exceptionHandler != null) {
            throw new IllegalStateException("Cannot specify both an exception handler and SUSPEND_EXISTING");
        }
        TransactionManager transactionManager = getTransactionManager();
        Transaction transaction = null;
        try {
            if (isTransactionActive()) {
                transaction = transactionManager.suspend();
            }
            T result = task.call();
            if (transaction != null) {
                try {
                    transactionManager.resume(transaction);
                    transaction = null;
                } catch (Exception e) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Use one of the documented TransactionSemantics values (REQUIRED, REQUIRES_NEW, SUPPORTS, MANDATORY, NEVER, NOT_SUPPORTED, JOIN_EXISTING, SUSPEND_EXISTING, DISALLOW_EXISTING)
2. Align extension and Quarkus versions so enum and implementation match
3. Check for null semantics being passed (add explicit null handling in caller)

Objects.requireNonNull(semantics, "TransactionSemantics must not be null");
if (!KNOWN_SEMANTICS.contains(semantics)) {
    throw new IllegalArgumentException("Unsupported semantics: " + semantics);
}

try {
    QuarkusTransaction.call(runOptions, task);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Unknown semantics")) {
        log.error("Check TransactionSemantics value and Quarkus version alignment");
    }
    throw e;
}

When it happens

Trigger: Invoking QuarkusTransaction.call/run with a TransactionSemantics that the switch statement does not cover; only possible via a non-standard enum value or if the implementation lags a newly added enum constant.

Common situations: Library version mismatch where an extension passes a newer enum constant to an older QuarkusTransactionImpl; reflection/proxy-based invocation passing null or unhandled semantics.

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

• seconds cannot be negative
• Cannot specify both an exception handler and SUSPEND_EXISTIN
• Transaction already active
• Transaction already active
• Unsupported value:

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