provectus/kafka-ui · error · ValidationException

'name' property not set for serde

Error message

'name' property not set for serde: ${serdeConfig}

What it means

SerdesInitializer.init validates each serde entry from kafka.clusters.<n>.serde configuration. Every serde must have a non-empty name; if the name is null/empty the initializer throws ValidationException so the application fails at startup with a clear config error.

Solutions

1. Add a unique 'name' to the serde entry in the cluster config
2. Check YAML indentation so the name key is nested under the correct serde item
3. If constructing SerdeConfig in code, call setName(...) before registration

Example fix

// before (application.yaml)
serde:
  - className: com.example.MySerde
    filePath: /opt/serdes/my-serde.jar
// after
serde:
  - name: my-serde
    className: com.example.MySerde
    filePath: /opt/serdes/my-serde.jar

clusterProperties.getSerde().forEach(s -> {
  if (Strings.isNullOrEmpty(s.getName()))
    throw new IllegalArgumentException("serde entry missing name: " + s);
});

try {
  serdes = initializer.init(...);
} catch (ValidationException e) {
  log.error("Invalid serde config: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: A serde entry in application.yaml/properties omits the 'name' field (or sets it to an empty string) while other fields like className/filePath are present.

Common situations: YAML indentation mistakes that drop the name key; copy-pasted serde blocks with the name accidentally deleted; programmatic SerdeConfig construction without setName.

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

• Multiple serdes with same name
• className can't be set for built-in serde
• filePath can't be set for built-in serde types
• serde is not configured
• filePath can't be set for built-in serde type

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

Appendix: source

Thrown at kafka-ui-api/src/main/java/com/provectus/kafka/ui/serdes/SerdesInitializer.java:101

   * trying to auto-configure them and  registering with empty patterns - they will be present
   * in Serde selection in UI, but not assigned to any topic k/v.
   */
  public ClusterSerdes init(Environment env,
                            ClustersProperties clustersProperties,
                            int clusterIndex) {
    ClustersProperties.Cluster clusterProperties = clustersProperties.getClusters().get(clusterIndex);
    log.debug("Configuring serdes for cluster {}", clusterProperties.getName());

    var globalPropertiesResolver = new PropertyResolverImpl(env);
    var clusterPropertiesResolver = new PropertyResolverImpl(env, "kafka.clusters." + clusterIndex);

    Map<String, SerdeInstance> registeredSerdes = new LinkedHashMap<>();
    // initializing serdes from config
    if (clusterProperties.getSerde() != null) {
      for (int i = 0; i < clusterProperties.getSerde().size(); i++) {
        SerdeConfig serdeConfig = clusterProperties.getSerde().get(i);
        if (Strings.isNullOrEmpty(serdeConfig.getName())) {
          throw new ValidationException("'name' property not set for serde: " + serdeConfig);
        }
        if (registeredSerdes.containsKey(serdeConfig.getName())) {
          throw new ValidationException("Multiple serdes with same name: " + serdeConfig.getName());
        }
        var instance = createSerdeFromConfig(
            serdeConfig,
            new PropertyResolverImpl(env, "kafka.clusters." + clusterIndex + ".serde." + i + ".properties"),
            clusterPropertiesResolver,
            globalPropertiesResolver
        );
        registeredSerdes.put(serdeConfig.getName(), instance);
      }
    }

    // initializing remaining built-in serdes with empty selection patters
    builtInSerdeClasses.forEach((name, clazz) -> {
      if (!registeredSerdes.containsKey(name)) {
        BuiltInSerde serde = createSerdeInstance(clazz);

View on GitHub (pinned to 83b5a60cc0)