eclipse-vertx/vert.x · error · IllegalArgumentException

The server must be configured with a token validation key to

Error message

The server must be configured with a token validation key to operate address validation

What it means

QUIC server configuration inconsistency in createCodecBuilder: address validation is enabled (clientAddressValidation != NONE) but no token handler and no token validation key was configured, so the server cannot issue/validate address-validation tokens. The inputs at fault are QuicServerOptions.clientAddressValidation and the missing token key configuration.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/quic/QuicServerImpl.java:203

    QuicSslContextBuilder sslContextBuilder = QuicSslContextBuilder
      .forServer(SNI_KEYMANAGER, null)
      .clientAuth(ClientAuth.REQUIRE)
      .sni(mapping);
    sslContextBuilder.keylog(keylog);
    if (sslOptions.getClientAuth() != null) {
      sslContextBuilder.clientAuth(SslContextManager.mapClientAuth(sslOptions.getClientAuth()));
    }
    QuicSslContext sslContext = sslContextBuilder.build();
    QuicTokenHandler qtc = tokenHandler;
    if (qtc == null) {
      switch (config.getClientAddressValidation()) {
        case BASIC:
          qtc = InsecureQuicTokenHandler.INSTANCE;
          break;
        case CRYPTO:
          KeyCertOptions tokenValidationKey = config.getClientAddressValidationKey();
          if (tokenValidationKey == null) {
            throw new IllegalArgumentException("The server must be configured with a token validation key to operate address validation");
          }
          Duration timeWindow = config.getClientAddressValidationTimeWindow();
          TokenManager tokenManager = new TokenManager(vertx, timeWindow);
          tokenManager.init(tokenValidationKey);
          qtc = tokenManager;
          break;
      }
    }
    QuicServerCodecBuilder builder = new QuicServerCodecBuilder().sslContext(sslContext)
      .tokenHandler(qtc)
      .handler(new ChannelInitializer<>() {
        @Override
        protected void initChannel(Channel ch) {
          connectionGroup.add(ch);
          QuicChannel channel = (QuicChannel) ch;
          LogConfig logConfig = config.getLogConfig();
          ByteBufFormat activityLogging = logConfig != null && logConfig.isEnabled() ? logConfig.getDataFormat() : null;
          Completable<QuicConnection> adapter = (result, failure) -> {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Configure the QUIC token validation key on the server options
2. Provide a custom QuicTokenHandler
3. Set clientAddressValidation to NONE to disable validation

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/quic/QuicServerImpl.java:203 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/ad1d320b64762fbc. Report an issue: GitHub.