quarkusio/quarkus · error · IllegalArgumentException

listener must not be null

Error message

listener must not be null

What it means

TraceManagerImpl.addTraceListener rejects null listeners with IllegalArgumentException. The trace manager keeps a list of listeners notified on template lifecycle events, and a null entry would break event dispatch.

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/TraceManagerImpl.java:29

 *
 */
class TraceManagerImpl implements TraceManager {

    private final List<TraceListener> listeners;

    TraceManagerImpl() {
        listeners = new CopyOnWriteArrayList<>();
    }

    /**
     * Registers a new trace listener.
     *
     * @param listener the listener to add
     */
    @Override
    public void addTraceListener(TraceListener listener) {
        if (listener == null) {
            throw new IllegalArgumentException("listener must not be null");
        }
        listeners.add(listener);
    }

    /**
     * Removes a previously registered trace listener.
     *
     * @param listener the listener to remove
     */
    @Override
    public void removeTraceListener(TraceListener listener) {
        if (listener == null) {
            throw new IllegalArgumentException("listener must not be null");
        }
        listeners.remove(listener);
    }

    /**

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure a non-null TraceListener instance is constructed before registration.
2. If the listener is optional, guard with a null check and skip registration.
3. Verify the listener bean/lookup actually resolves (e.g. CDI select returns a bean) before adding.

Example fix

// before
TraceListener listener = config.listenerOrNull();
traceManager.addTraceListener(listener); // NPE source: null

// after
TraceListener listener = config.listenerOrNull();
if (listener != null) {
    traceManager.addTraceListener(listener);
}

if (listener == null) {
    return; // or log a warning: no trace listener configured
}
traceManager.addTraceListener(listener);

static boolean isValidListener(TraceListener l) {
    return l != null;
}

try {
    traceManager.addTraceListener(listener);
} catch (IllegalArgumentException e) {
    if ("listener must not be null".equals(e.getMessage())) {
        // skip registration; listener was not configured
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling engine.getTraceManager().addTraceListener(null), often when the listener is the result of an unassigned field, an unresolved bean/lookup, or an optional callback that is null.

Common situations: CDI injection returning null (e.g. @Inject field not satisfied in tests), a config-driven listener that failed to instantiate, or passing a lambda stored in a nullable holder.

Related errors

• Literal must not be null
• Contextual parameter must not be null
• `member` cannot be `null`
• `unit` cannot be `null`
• `" + name + "` must not be `null`

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