provectus/kafka-ui · critical · IllegalStateException

Application config isn't valid. Cluster names should be…

Error message

Application config isn't valid. Cluster names should be provided in case of multiple clusters present

What it means

At application startup, ClustersProperties.validateClusterNames enforces that when more than one Kafka cluster is configured in the `kafka.clusters` list, every cluster entry must have a non-blank `name`. It throws IllegalStateException during config validation (validateAndSetDefaults) so the app fails fast rather than running with ambiguous cluster references.

Solutions

Add a unique `name` field to every cluster entry under kafka.clusters in your application config
Keep a `name` even for a single cluster so later additions can't break startup
Validate the YAML locally (e.g. run the app with only config loading) before deploying

Example fix

// before
kafka:
  clusters:
    - bootstrapServers: broker1:9092
    - bootstrapServers: broker2:9092
// after
kafka:
  clusters:
    - name: dev
      bootstrapServers: broker1:9092
    - name: prod
      bootstrapServers: broker2:9092

Defensive patterns

Strategy: validation

Validate before calling

clusters = config['kafka']['clusters']
if len(clusters) > 1:
    missing = [i for i, c in enumerate(clusters) if not c.get('name', '').strip()]
    if missing:
        raise ValueError(f'clusters missing name at indices: {missing}')

Try / catch

try:
    app = buildApp(config)
except IllegalStateException as e:
    log.error('Cluster config invalid: {}', e.message)
    raise SystemExit(1)

Prevention

Always set a name for every cluster, even with a single cluster
Lint application.yml in CI for required kafka.clusters[].name fields
Use a config schema validator before deploy

When it happens

Trigger: Spring context startup with kafka.clusters containing 2+ entries and at least one entry without a `name` property (blank, empty, or missing).

Common situations: Adding a second cluster to application.yml/properties and forgetting the name because a single anonymous cluster worked before; YAML indentation mistakes leaving `name` unset; generating config from templates that omit name for the first cluster.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of provectus/kafka-ui@83b5a60cc0 (2026-09-08). Data as JSON: /api/errors/187ea02a826d6172. Report an issue: GitHub.

Appendix: source

Thrown at kafka-ui-api/src/main/java/com/provectus/kafka/ui/config/ClustersProperties.java:211

        } else {
          flattened.put(key, v);
        }
      });
    }
    return flattened;
  }

  private void validateClusterNames() {
    // if only one cluster provided it is ok not to set name
    if (clusters.size() == 1 && !StringUtils.hasText(clusters.get(0).getName())) {
      clusters.get(0).setName("Default");
      return;
    }

    Set<String> clusterNames = new HashSet<>();
    for (Cluster clusterProperties : clusters) {
      if (!StringUtils.hasText(clusterProperties.getName())) {
        throw new IllegalStateException(
            "Application config isn't valid. "
                + "Cluster names should be provided in case of multiple clusters present");
      }
      if (!clusterNames.add(clusterProperties.getName())) {
        throw new IllegalStateException(
            "Application config isn't valid. Two clusters can't have the same name");
      }
    }
  }
}

View on GitHub (pinned to 83b5a60cc0)