quarkusio/quarkus · error · RuntimeException

Only one handler can be configured with the same name

Error message

Only one handler can be configured with the same name '%s'

What it means

When building named log handlers from configuration, addToNamedHandlers refuses to add two handlers with the same handler name, throwing a RuntimeException with 'Only one handler can be configured with the same name'. Handler names must be unique because they are map keys used to route category handlers.

Solutions

1. Give each configured handler a unique name in application.properties
2. Remove the duplicate handler configuration block
3. If handlers are created programmatically, ensure createNamedHandlers/addToNamedHandlers is called once per handler with a distinct name

Example fix

// before
quarkus.log.handler.console."a".name=LOG
quarkus.log.handler.file."f".name=LOG
// after
quarkus.log.handler.console."a".name=CONSOLE_LOG
quarkus.log.handler.file."f".name=FILE_LOG

// pre-validate handler names in config are unique
Set<String> seen = new HashSet<>();
for (String name : configuredHandlerNames()) { if (!seen.add(name)) throw new IllegalArgumentException("Duplicate handler name: " + name); }

try { configureLogging(); } catch (RuntimeException e) { if (e.getMessage().contains("Only one handler can be configured with the same name")) log.error("Handler names must be unique: " + e.getMessage()); else throw e; }

When it happens

Trigger: Two handler configuration blocks in application.properties resolve to the same handler name, or a category references/creates the same named handler twice (e.g. quarkus.log.handler.console."x".name duplicated across console/file/syslog handlers).

Common situations: Copy-pasted handler config blocks with identical name properties; generating handler configs programmatically where names collide; merging configuration profiles that both define the same named handler.

Related errors

• Duplicate key (attempted merging values and )
• No OTLP protocol specified. Please check…
• Unable to convert (obtained from the system property) into…
• Unable to create instance of Logging Filter ''
• Unsupported OTLP protocol

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

Appendix: source

Thrown at core/runtime/src/main/java/io/quarkus/runtime/logging/LoggingSetupRecorder.java:532

        if (additionalNamedHandlers.isEmpty()) {
            additionalNamedHandlersMap = emptyMap();
        } else {
            additionalNamedHandlersMap = new HashMap<>();
            for (RuntimeValue<Map<String, Handler>> runtimeValue : additionalNamedHandlers) {
                runtimeValue.getValue().forEach(
                        new AdditionalNamedHandlersConsumer(additionalNamedHandlersMap, errorManager,
                                cleanupFilter.filterElements.values(), shutdownHandler));
            }
        }

        namedHandlers.putAll(additionalNamedHandlersMap);

        return namedHandlers;
    }

    private static void addToNamedHandlers(Map<String, Handler> namedHandlers, Handler handler, String handlerName) {
        if (namedHandlers.containsKey(handlerName)) {
            throw new RuntimeException(String.format("Only one handler can be configured with the same name '%s'",
                    handlerName));
        }
        namedHandlers.put(handlerName, handler);
        InitialConfigurator.DELAYED_HANDLER.addLoggingCloseTask(new Runnable() {
            @Override
            public void run() {
                handler.close();
            }
        });
    }

    private static void addNamedHandlersToCategory(
            CategoryConfig categoryConfig, Map<String, Handler> namedHandlers,
            Logger categoryLogger,
            ErrorManager errorManager,
            boolean checkHandlerLinks) {
        for (String categoryNamedHandler : categoryConfig.handlers().get()) {
            Handler handler = namedHandlers.get(categoryNamedHandler);

View on GitHub (pinned to e1c734241f)