{"record":{"id":"bb618b61ea67125f","repo":"provectus/kafka-ui","slug":"filepath-property-not-set-for-custom-serde-ser","errorCode":null,"errorMessage":"'filePath' property not set for custom serde ${serdeConfig.getName()}","messagePattern":"'filePath' property not set for custom serde (.+?)","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"kafka-ui-api/src/main/java/com/provectus/kafka/ui/serdes/SerdesInitializer.java","lineNumber":263,"sourceCode":"        null\n    );\n  }\n\n  @SneakyThrows\n  private <T extends Serde> T createSerdeInstance(Class<T> clazz) {\n    return clazz.getDeclaredConstructor().newInstance();\n  }\n\n  private SerdeInstance loadAndInitCustomSerde(SerdeConfig serdeConfig,\n                                               PropertyResolver serdeProps,\n                                               PropertyResolver clusterProps,\n                                               PropertyResolver globalProps) {\n    if (Strings.isNullOrEmpty(serdeConfig.getClassName())) {\n      throw new ValidationException(\n          \"'className' property not set for custom serde \" + serdeConfig.getName());\n    }\n    if (Strings.isNullOrEmpty(serdeConfig.getFilePath())) {\n      throw new ValidationException(\n          \"'filePath' property not set for custom serde \" + serdeConfig.getName());\n    }\n    var loaded = customSerdeLoader.loadAndConfigure(\n        serdeConfig.getClassName(), serdeConfig.getFilePath(), serdeProps, clusterProps, globalProps);\n    return new SerdeInstance(\n        serdeConfig.getName(),\n        loaded.getSerde(),\n        nullablePattern(serdeConfig.getTopicKeysPattern()),\n        nullablePattern(serdeConfig.getTopicValuesPattern()),\n        loaded.getClassLoader()\n    );\n  }\n\n  @Nullable\n  private Pattern nullablePattern(@Nullable String pattern) {\n    return pattern == null ? null : Pattern.compile(pattern);\n  }\n}","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/provectus/kafka-ui/blob/83b5a60cc08501b570a0c4d0b4cdfceb1b88d6b7/kafka-ui-api/src/main/java/com/provectus/kafka/ui/serdes/SerdesInitializer.java#L245-L281","documentation":"Kafka UI's SerdesInitializer validates every custom serde config before loading it. A custom serde must specify both the fully-qualified 'className' of the Serde implementation and the 'filePath' of the JAR containing it; when filePath is null or empty the initializer refuses to proceed because the class cannot be located without its archive. It throws a ValidationException naming the offending serde.","triggerScenarios":"Calling createSerdeFromConfig / loadAndInitCustomSerde with a CustomSerde config whose filePath property is missing, empty, or set to null (e.g. only className was specified in serdeConfig).","commonSituations":"Hand-writing serde config in application.yaml/properties and forgetting the filePath key; copying a serde config snippet that only sets className; programmatically building a CustomSerde and leaving filePath unset.","solutions":["Add the 'filePath' property pointing to the custom serde JAR to the serde config","Verify the property name spelling (filePath) and that the value is non-empty in application.yaml or the API request payload","If the JAR is bundled, set filePath to its classpath-relative or absolute path accessible to the kafka-ui process"],"exampleFix":"// before\nserde:\n  - name: my-serde\n    className: com.example.MySerde\n// after\nserde:\n  - name: my-serde\n    className: com.example.MySerde\n    filePath: /etc/kafka-ui/serde/my-serde.jar","handlingStrategy":"validation","validationCode":"if (cfg == null || cfg.getClassName() == null || cfg.getClassName().isBlank() || cfg.getFilePath() == null || cfg.getFilePath().isBlank()) { throw new IllegalArgumentException(\"custom serde needs both className and filePath\"); }","typeGuard":"boolean isValidCustomSerde(c) { return c != null && !isNullOrEmpty(c.getClassName()) && !isNullOrEmpty(c.getFilePath()); }","tryCatchPattern":"try { serde = initCustomSerde(cfg); } catch (ValidationException e) { log.error(\"bad serde config: {}\", e.getMessage()); }","preventionTips":["Always set filePath (JAR location) whenever className is set for a custom serde","Validate serde config keys against a schema at startup","Keep serde JAR paths in one well-documented config section"],"tags":["configuration","serde","validation"],"backgroundTag":"missing-required-config-field","analyzedSha":"83b5a60cc08501b570a0c4d0b4cdfceb1b88d6b7","analyzedAt":"2026-09-08T04:35:39.002Z","contentChangedAt":"2026-09-08T04:35:39.002Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}