provectus/kafka-ui · critical · IllegalStateException

Application config isn't valid. Two clusters can't have the…

Error message

Application config isn't valid. Two clusters can't have the same name

What it means

validateClusterNames rejects duplicate cluster names: it collects each cluster's `name` into a Set, and if Set.add returns false (name already seen) it throws IllegalStateException. Kafka UI identifies clusters by name in URLs and API paths, so duplicates are ambiguous and the app refuses to start.

Solutions

Give each kafka.clusters entry a distinct `name` value
Search your config for duplicated `name:` values under kafka.clusters
If names come from env vars, ensure each environment supplies a different CLUSTER_NAME

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

names = [c.get('name') for c in config['kafka']['clusters']]
if len(names) != len(set(names)):
    dupes = {n for n in names if names.count(n) > 1}
    raise ValueError(f'Duplicate cluster names: {dupes}')

Try / catch

try:
    app = buildApp(config)
except IllegalStateException as e:
    log.error('Duplicate cluster names in config: {}', e.message)
    raise SystemExit(1)

Prevention

Copy-paste checklist: change name whenever duplicating a cluster block
Generate names from environment identifiers rather than hardcoding
Add a uniqueness assertion in your config test suite

When it happens

Trigger: Application startup when two or more entries under kafka.clusters share the exact same `name` value.

Common situations: Copy-pasting an existing cluster block to add a new environment and forgetting to change the name; environment-variable templating that renders the same name for all clusters; merging config files that both define a cluster named e.g. 'dev'.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

    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)