quarkusio/quarkus · error · IllegalStateException

Tracing not enabled

Error message

Tracing not enabled

What it means

Engine.addTraceListener() registers a TraceListener with the engine's TraceManager. Tracing is an opt-in engine feature; if the engine was built without trace support getTraceManager() returns null and this IllegalStateException is thrown.

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/Engine.java:205

     * Returns the {@link TraceManager} responsible for managing trace listeners and
     * firing trace events during template rendering.
     *
     * @return the trace manager instance or {@code null} if tracing is disabled
     * @see EngineBuilder#enableTracing(boolean)
     */
    TraceManager getTraceManager();

    /**
     * Registers a new {@link TraceListener} to receive trace events.
     * <p>
     * The listener will be notified of template rendering and resolution events.
     *
     * @param listener the trace listener to add; must not be {@code null}
     */
    default void addTraceListener(TraceListener listener) {
        TraceManager manager = getTraceManager();
        if (manager == null) {
            throw new IllegalStateException("Tracing not enabled");
        }
        manager.addTraceListener(listener);
    }

    /**
     * Unregisters a previously registered {@link TraceListener}.
     * <p>
     * After removal, the listener will no longer receive trace events.
     *
     * @param listener the trace listener to remove; must not be {@code null}
     */
    default void removeTraceListener(TraceListener listener) {
        TraceManager manager = getTraceManager();
        if (manager == null) {
            throw new IllegalStateException("Tracing not enabled");
        }
        manager.removeTraceListener(listener);
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Enable tracing when building the engine: builder.traceManager(new TraceManager()) (or the builder's trace-enabling API) before build()
2. Check engine.getTraceManager() != null before registering listeners
3. If tracing is not needed, remove the listener registration call

Example fix

// before
Engine engine = Engine.builder().addDefaults().build();
engine.addTraceListener(listener); // throws
// after
Engine engine = Engine.builder().addDefaults().traceManager(new TraceManager()).build();
engine.addTraceListener(listener);

if (engine.getTraceManager() == null) {
    throw new IllegalStateException("Enable tracing on the EngineBuilder before adding trace listeners");
}

boolean tracingEnabled(Engine engine) { return engine.getTraceManager() != null; }

try {
    engine.addTraceListener(listener);
} catch (IllegalStateException e) {
    // tracing disabled — rebuild engine with a TraceManager or skip registration
}

When it happens

Trigger: Calling engine.addTraceListener(listener) on an Engine built without trace enabled (no TraceManager configured via EngineBuilder).

Common situations: Developers adding template debugging/tracing after building the engine with plain Engine.builder() without enabling tracing, or in tests that assume tracing is on by default.

Related errors

• Not a virtual method: [typeInfo: ]
• No suitable template variant found
• No template variant found
• Class [<rawClassName>] used in the parameter declaration in
• #cache cannot be used without the 'quarkus-cache' extension

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