{"record":{"id":"75cd9602d25a0532","repo":"quarkusio/quarkus","slug":"the-tls-configuration-name-default-cannot-be-use","errorCode":null,"errorMessage":"The TLS configuration name <default> cannot be used explicitly in configuration or qualifiers","messagePattern":"The TLS configuration name <default> cannot be used explicitly in configuration or qualifiers","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/CertificateRecorder.java","lineNumber":78,"sourceCode":"     * @param vertx the Vert.x instance\n     */\n    public void validateCertificates(Set<String> providerBucketNames,\n            RuntimeValue<Vertx> vertx,\n            ShutdownContext shutdownContext) {\n        this.vertx = vertx.getValue();\n        // Verify the default config\n        if (runtimeConfig.getValue().defaultCertificateConfig().isPresent()) {\n            verifyCertificateConfig(runtimeConfig.getValue().defaultCertificateConfig().get(), vertx.getValue(),\n                    TlsConfig.DEFAULT_NAME);\n        }\n\n        var bucketNames = new HashSet<>(runtimeConfig.getValue().namedCertificateConfig().keySet());\n        bucketNames.addAll(providerBucketNames);\n\n        // Verify the named configs\n        for (String name : bucketNames) {\n            if (name.equals(TlsConfig.DEFAULT_NAME)) {\n                throw new IllegalArgumentException(\n                        \"The TLS configuration name \" + TlsConfig.DEFAULT_NAME\n                                + \" cannot be used explicitly in configuration or qualifiers\");\n            }\n            if (name.equals(TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME)) {\n                throw new IllegalArgumentException(\n                        \"The TLS configuration name \" + TlsConfig.JAVA_NET_SSL_TLS_CONFIGURATION_NAME\n                                + \" is reserved for providing access to default SunJSSE keystore; neither Quarkus extensions nor end users can adjust or override it\");\n            }\n            verifyCertificateConfig(runtimeConfig.getValue().namedCertificateConfig().get(name), vertx.getValue(), name);\n        }\n\n        shutdownContext.addShutdownTask(new Runnable() {\n            @Override\n            public void run() {\n                if (reloader != null) {\n                    reloader.close();\n                }\n            }","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/CertificateRecorder.java#L60-L96","documentation":"The TLS registry reserves the name <default> for the implicitly-registered default TLS configuration. At startup, CertificateRecorder.validateCertificates() scans all named quarkus.tls.key-store.*-style certificate configs and fails fast if any is explicitly named <default>, because named configurations must use a distinct name while the default is reached by omitting the name. This is a configuration validation error thrown as IllegalArgumentException during static init/startup.","triggerScenarios":"A quarkus.tls.key-store.\"<default>\".* or quarkus.tls.trust-store.\"<default>\".* property block is set in application.properties/yaml, an environment variable expands to the <default> key, or a TlsConfig/qualifier references the default name explicitly.","commonSituations":"Copy-pasting an example named TLS config block and leaving the name as <default>; renaming an existing named config to <default> hoping to override the default config; YAML/properties quoting confusion where the bucket key literally becomes <default>.","solutions":["Remove the <default> named block and configure the default TLS configuration with unnamed properties (quarkus.tls.key-store.*) instead","Rename the configuration to a custom name (e.g. my-tls) and reference it via the matching qualifier/config name","Check property keys, including env-var forms like QUARKUS_TLS_KEY_STORE____DEFAULT__, for the literal <default> name"],"exampleFix":"// before (application.properties)\nquarkus.tls.key-store.\"<default>\".paths=tls/server.pem\n// after\nquarkus.tls.key-store.paths=tls/server.pem","handlingStrategy":"validation","validationCode":"Set<String> names = ConfigProvider.getConfig().getPropertyNames();\nif (names.stream().anyMatch(p -> p.startsWith(\"quarkus.tls.\") && p.contains(\"<default>\"))) {\n    throw new IllegalStateException(\"TLS config must not be named <default>; use unnamed quarkus.tls.* properties\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    // application startup / config registration\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"cannot be used explicitly\")) {\n        log.error(\"Fix TLS config naming: remove the <default> named block\", e);\n    } else { throw e; }\n}","preventionTips":["Configure the default TLS config with unnamed quarkus.tls.key-store.*/trust-store.* properties","Never quote <default> or <java-net-ssl> as a named bucket key","Grep application.properties/yaml and env vars for the literal string <default> before startup"],"tags":["quarkus","tls","configuration","startup"],"backgroundTag":"reserved-config-name","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}