quarkusio/quarkus · error · IllegalArgumentException

The name of the TLS configuration to register cannot be null

Error message

The name of the TLS configuration to register cannot be null

What it means

TlsConfigurationRegistry.register(name, configuration) requires a non-null name because every registered configuration must be retrievable by name. A null name cannot be resolved later and would corrupt registry lookups, so register() throws IllegalArgumentException immediately.

Source

Thrown at extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/CertificateRecorder.java:214

        if (TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME.equals(name)) {
            final TlsConfiguration result = certificates.computeIfAbsent(TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME, k -> {
                final TrustStoreAndTrustOptions ts = JavaxNetSslTrustStoreProvider.getTrustStore(vertx);
                return new VertxCertificateHolder(vertx, k, runtimeConfig.getValue().namedCertificateConfig().get(k), null, ts);
            });
            return Optional.ofNullable(result);
        }
        return Optional.ofNullable(certificates.get(name));
    }

    @Override
    public Optional<TlsConfiguration> getDefault() {
        return get(TlsConfig.DEFAULT_NAME);
    }

    @Override
    public void register(String name, TlsConfiguration configuration) {
        if (name == null) {
            throw new IllegalArgumentException("The name of the TLS configuration to register cannot be null");
        }
        if (name.equals(TlsConfig.DEFAULT_NAME)) {
            throw new IllegalArgumentException("The name of the TLS configuration to register cannot be <default>");
        }
        if (name.equals(TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME)) {
            throw new IllegalArgumentException(
                    "The TLS configuration name " + TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME
                            + " is reserved for providing access to default SunJSSE keystore; neither Quarkus extensions nor end users can adjust of override it");
        }
        if (configuration == null) {
            throw new IllegalArgumentException("The TLS configuration to register cannot be null");
        }
        certificates.put(name, configuration);
    }

    public Supplier<TlsConfigurationRegistry> getSupplier() {
        return new Supplier<TlsConfigurationRegistry>() {
            @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass an explicit non-null name, or use the no-arg/default registration path for the default configuration
2. Null-check or default the config-derived name before calling register (e.g. Objects.requireNonNullElse(name, "my-tls"))
3. If the intent was the default config, call register with a valid name or use the dedicated default accessor instead

Example fix

// before
registry.register(config.name(), configuration); // name() may be null
// after
String name = config.name();
if (name == null) { name = "my-tls"; }
registry.register(name, configuration);

if (name == null || name.isBlank()) {
    throw new IllegalArgumentException("TLS configuration name must be a non-null, non-blank string");
}

static boolean isValidTlsName(String name) {
    return name != null && !name.isBlank();
}
// usage: if (isValidTlsName(name)) { registry.register(name, config); }

try {
    registry.register(name, configuration);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot be null")) {
        log.error("Provide an explicit non-null name for the TLS configuration", e);
    } else { throw e; }
}

When it happens

Trigger: An extension or application code calls tlsConfigurationRegistry.register(null, configuration), typically when the name is derived from a nullable config value or a variable that was never initialized.

Common situations: Custom extensions registering TLS configurations whose name comes from an optional config property that is absent; refactoring where a name constant was replaced by a null-returning lookup.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• The name of the TLS configuration to register cannot be <def
• A generic type is not allowed here; try creating a subclass
• Build item class must be leaf (final) types: %s
• Cannot construct empty build items
• A build step must be a non-static method: %s

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