quarkusio/quarkus · error · IllegalArgumentException

Unsupported value:

Error message

Unsupported value: 

What it means

Thrown when an invalid TransactionSemantics enum value is passed to RunOptions.semantics() on the narayana-jta extension. The switch in the builder only handles REQUIRE_NEW, JOIN_EXISTING and SUSPEND_EXISTING; anything else (e.g. a null or foreign enum) falls into the default branch. It is a programmer-error guard, not a runtime condition.

Source

Thrown at extensions/narayana-jta/runtime/src/main/java/io/quarkus/narayana/jta/RunOptions.java:54

        if (semantic == null) {
            setSemantics(null);
            return this;
        }
        switch (semantic) {
            case DISALLOW_EXISTING:
                setSemantics(TransactionSemantics.DISALLOW_EXISTING);
                break;
            case JOIN_EXISTING:
                setSemantics(TransactionSemantics.JOIN_EXISTING);
                break;
            case REQUIRE_NEW:
                setSemantics(TransactionSemantics.REQUIRE_NEW);
                break;
            case SUSPEND_EXISTING:
                setSemantics(TransactionSemantics.SUSPEND_EXISTING);
                break;
            default:
                throw new IllegalArgumentException("Unsupported value: " + semantic);
        }
        return this;
    }

    /**
     * Provides an exception handler that can make a decision to rollback or commit based on the type of exception. If the
     * predicate returns {@link ExceptionResult#ROLLBACK} the transaction is rolled back,
     * otherwise it is committed.
     * <p>
     * This exception will still be propagated to the caller, so this method should not log or perform any other actions other
     * than determine what should happen to the current transaction.
     * <p>
     * By default, the exception is always rolled back.
     *
     * @param handler The exception handler
     * @return This builder
     */
    public RunOptions exceptionHandler(Function<Throwable, ExceptionResult> handler) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass exactly one of TransactionSemantics.REQUIRE_NEW, JOIN_EXISTING or SUSPEND_EXISTING
2. If converting from a string, validate it first via TransactionSemantics.valueOf inside its own try-catch and fall back to a safe default
3. Check the TransactionSemantics enum in your Quarkus version for the exact set of allowed values

Example fix

// before
RunOptions opts = new RunOptions().semantics(TransactionSemantics.valueOf(input));
// after
TransactionSemantics s;
try { s = TransactionSemantics.valueOf(input); } catch (IllegalArgumentException e) { s = TransactionSemantics.REQUIRE_NEW; }
RunOptions opts = new RunOptions().semantics(s);

if (semantics != TransactionSemantics.REQUIRE_NEW && semantics != TransactionSemantics.JOIN_EXISTING && semantics != TransactionSemantics.SUSPEND_EXISTING) throw new IllegalArgumentException("Unsupported semantics: " + semantics);

boolean isValidSemantics(TransactionSemantics s) { return s == TransactionSemantics.REQUIRE_NEW || s == TransactionSemantics.JOIN_EXISTING || s == TransactionSemantics.SUSPEND_EXISTING; }

try { opts = new RunOptions().semantics(s); } catch (IllegalArgumentException e) { opts = new RunOptions(); /* default semantics */ }

When it happens

Trigger: Calling RunOptions semaphore API: new RunOptions().semantics(<value not one of TransactionSemantics.REQUIRE_NEW / JOIN_EXISTING / SUSPEND_EXISTING>), e.g. a null enum constant or a custom/renamed enum value.

Common situations: Refactoring/rename of TransactionSemantics leaving a stale constant; dynamic enum lookup by string (TransactionSemantics.valueOf(userInput)) returning an unexpected constant; copying code between Quarkus versions where enum members changed.

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
• Unknown semantics
• The Narayana JTA extension is configured to use the '%s' JDB
• The transaction is not active!
• No active transaction on the current thread

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