provectus/kafka-ui · error · ValidationException

filePath can't be set for built-in serde types

Error message

filePath can't be set for built-in serde types

What it means

Built-in serdes are compiled into kafka-ui and loaded from the application classpath; a filePath (external jar/directory) is meaningless for them, so createSerdeWithBuiltInSerdeName throws ValidationException when filePath is set alongside a built-in serde name.

Solutions

  1. Remove the filePath field from the built-in serde entry
  2. If an external jar is truly needed, rename the serde so it is not treated as built-in

Example fix

// before
serde:
  - name: avro-schema-registry
    filePath: /opt/serdes/extra.jar
// after
serde:
  - name: avro-schema-registry
Defensive patterns

Strategy: validation

Validate before calling

if (isBuiltInSerdeName(cfg.getName()) && cfg.getFilePath() != null)
  throw new IllegalArgumentException("filePath not allowed for built-in serde " + cfg.getName());

Try / catch

try {
  serde = createSerdeFromConfig(cfg, ...);
} catch (ValidationException e) {
  log.error("Bad serde config for {}: {}", cfg.getName(), e.getMessage());
  throw e;
}

Prevention

When it happens

Trigger: Config entry whose name matches a built-in serde and also sets filePath to a jar or directory.

Common situations: Applying the custom-serde config template (which includes filePath) to a built-in serde; misunderstanding that filePath is only for custom, external serdes.

Related errors

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

Appendix: source

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

      // built-in serde type with custom name
      if (builtInSerdeClass.isPresent()) {
        return createSerdeWithBuiltInClass(builtInSerdeClass.get(), serdeConfig, serdeProps, clusterProps, globalProps);
      }
    }
    log.info("Loading custom serde {}", serdeConfig.getName());
    return loadAndInitCustomSerde(serdeConfig, serdeProps, clusterProps, globalProps);
  }

  private SerdeInstance createSerdeWithBuiltInSerdeName(SerdeConfig serdeConfig,
                                                        PropertyResolver serdeProps,
                                                        PropertyResolver clusterProps,
                                                        PropertyResolver globalProps) {
    String name = serdeConfig.getName();
    if (serdeConfig.getClassName() != null) {
      throw new ValidationException("className can't be set for built-in serde");
    }
    if (serdeConfig.getFilePath() != null) {
      throw new ValidationException("filePath can't be set for built-in serde types");
    }
    var clazz = builtInSerdeClasses.get(name);
    BuiltInSerde serde = createSerdeInstance(clazz);
    if (serdeConfig.getProperties() == null || serdeConfig.getProperties().isEmpty()) {
      if (!autoConfigureSerde(serde, clusterProps, globalProps)) {
        // no properties provided and serde does not support auto-configuration
        throw new ValidationException(name + " serde is not configured");
      }
    } else {
      // configuring serde with explicitly set properties
      serde.configure(serdeProps, clusterProps, globalProps);
    }
    return new SerdeInstance(
        name,
        serde,
        nullablePattern(serdeConfig.getTopicKeysPattern()),
        nullablePattern(serdeConfig.getTopicValuesPattern()),
        null

View on GitHub (pinned to 83b5a60cc0)