provectus/kafka-ui · error · IllegalStateException

Location does not exist

Error message

Location does not exist

What it means

CustomSerdeLoader.createClassloader builds a URLClassLoader from a configured serde file location. Before scanning for archives it checks that the path exists; if the configured filePath directory/jar is absent on disk it throws IllegalStateException('Location does not exist') to fail fast at serde startup rather than at first use.

Solutions

1. Verify the configured filePath exists on the host running kafka-ui (ls the path in the container)
2. Fix the kafka.clusters.<cluster>.serde.filePath value to an existing directory/jar
3. Mount the serde archive into the container volume and align the configured path
4. Use an absolute path to avoid working-directory ambiguity

Example fix

// before
serde:
  - name: avro-custom
    filePath: /opt/serdes/custom-serde.jar   # not mounted in container
// after (jar mounted at /custom-serdes/)
serde:
  - name: avro-custom
    filePath: /custom-serdes/custom-serde.jar

Path loc = Path.of(cfg.getFilePath());
if (!Files.exists(loc)) throw new IllegalStateException("Serde location missing: " + loc);

try {
  serdeRegistry = initializer.init(...);
} catch (IllegalStateException e) {
  log.error("Custom serde load failed: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: Configuring a custom serde whose filePath points to a directory or archive that does not exist on the kafka-ui host (typo, wrong volume mount, file deleted).

Common situations: Docker/Kubernetes deployments where the serde jar is not mounted into the container; config written for another machine; relative paths resolved against a different working directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• No archive files were found
• 'name' property not set for serde
• Multiple serdes with same name
• className can't be set for built-in serde
• filePath can't be set for built-in serde types

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

Appendix: source

Thrown at kafka-ui-api/src/main/java/com/provectus/kafka/ui/serdes/CustomSerdeLoader.java:82

    if (isArchive(location)) {
      return List.of(location.toUri().toURL());
    }
    if (Files.isDirectory(location)) {
      List<URL> archiveFiles = new ArrayList<>();
      try (var files = Files.walk(location)) {
        var paths = files.filter(CustomSerdeLoader::isArchive).collect(Collectors.toList());
        for (Path path : paths) {
          archiveFiles.add(path.toUri().toURL());
        }
      }
      return archiveFiles;
    }
    return List.of();
  }

  private ClassLoader createClassloader(Path location) {
    if (!Files.exists(location)) {
      throw new IllegalStateException("Location does not exist");
    }
    var archives = findArchiveFiles(location);
    if (archives.isEmpty()) {
      throw new IllegalStateException("No archive files were found");
    }
    // we assume that location's content does not change during serdes creation
    // so, we can reuse already created classloaders
    return classloaders.computeIfAbsent(location, l ->
        AccessController.doPrivileged(
            (PrivilegedAction<URLClassLoader>) () ->
                new ChildFirstClassloader(
                    archives.toArray(URL[]::new),
                    CustomSerdeLoader.class.getClassLoader())));
  }

  //---------------------------------------------------------------------------------

  // This Classloader first tries to load classes by itself. If class not fount

View on GitHub (pinned to 83b5a60cc0)