{"record":{"id":"093885587d1dd7a2","repo":"eclipse-vertx/vert.x","slug":"invalid-configuration-093885","errorCode":null,"errorMessage":"Invalid configuration","messagePattern":"Invalid configuration","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/spi/tls/DefaultSslContextFactory.java","lineNumber":104,"sourceCode":"    return this;\n  }\n\n  @Override\n  public SslContextFactory keyMananagerFactory(KeyManagerFactory kmf) {\n    this.kmf = kmf;\n    return this;\n  }\n\n  @Override\n  public SslContextFactory trustManagerFactory(TrustManagerFactory tmf) {\n    this.tmf = tmf;\n    return this;\n  }\n\n  @Override\n  public SslContext create() throws SSLException {\n    if (forClient == forServer) {\n      throw new IllegalStateException(\"Invalid configuration\");\n    }\n    return createContext(useAlpn, forClient, kmf, tmf);\n  }\n\n  @Override\n  public SslContextFactory enabledCipherSuites(Set<String> enabledCipherSuites) {\n    this.enabledCipherSuites = enabledCipherSuites;\n    return this;\n  }\n\n  @Override\n  public SslContextFactory applicationProtocols(List<String> applicationProtocols) {\n    this.applicationProtocols = applicationProtocols;\n    return this;\n  }\n\n  /*\n        If you don't specify a trust store, and you haven't set system properties, the system will try to use either a file","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/spi/tls/DefaultSslContextFactory.java#L86-L122","documentation":"DefaultSslContextFactory.create() throws IllegalStateException when the factory has not been configured as either a client or a server factory (forClient == forServer). A factory can only build an SSLContext for one side of the connection, so using the factory without initializing it via a client/server setup path is an invalid configuration. This is a programming error, not an SSL/TLS handshake failure.","triggerScenarios":"Calling SslContextFactory.create() on a DefaultSslContextFactory that was never initialized with a client or server role, e.g. using the raw factory without going through SslContextFactory.client()/server() style configuration so forClient and forServer are both false (or both true, which cannot happen through normal APIs).","commonSituations":"Custom TLS setup code that constructs a DefaultSslContextFactory directly and forgets to call the client()/server() initializer; refactoring code that dropped the client/server configuration call; wiring a factory in DI without its role.","solutions":["Initialize the factory for a role before creating the context: use the factory's client configuration (forClient=true) when dialing out or server configuration (forServer=true) when binding a server.","Prefer the high-level Vert.x API (HttpServerOptions/HttpClientOptions with KeyCertOptions/TrustOptions) which configures the factory correctly; only build SslContextFactory manually when truly needed.","Fix the setup code path so create() is called exactly once, after role configuration."],"exampleFix":"// before\nSslContextFactory factory = new DefaultSslContextFactory();\nSslContext ctx = factory.create(); // IllegalStateException\n// after\nSslContextFactory factory = new DefaultSslContextFactory();\nfactory.client(); // or factory.server()\nSslContext ctx = factory.create();","handlingStrategy":"validation","validationCode":"if (factory instanceof DefaultSslContextFactory) { /* ensure role set */ }\n// Prefer: build via client()/server() options rather than raw factory; assert role before create\nboolean configured = /* role initialized via client()/server() */;\nif (!configured) throw new IllegalStateException(\"Set client or server role before create()\");","typeGuard":"boolean isConfigured(SslContextFactory f) { return f != null && (f.isClient() ^ f.isServer()); }","tryCatchPattern":"try { SslContext ctx = factory.create(); } catch (IllegalStateException e) { log.error(\"SSL factory used without client/server role\", e); }","preventionTips":["Never construct DefaultSslContextFactory directly; use Vert.x SSL options APIs","Always call the client/server initializer before create()","Cover TLS setup with a unit test that calls create()"],"tags":["ssl","tls","configuration","invalid-state"],"backgroundTag":"invalid-state-transition","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}