apache/pulsar · error · RuntimeException

Log folder creation error

Error message

Log folder creation error

What it means

ProcessRuntime.start() creates the function's log directory (funcLogDir) via Files.createDirectories before spawning the function process. If directory creation fails with an IOException (permissions, path is a file, filesystem full), it logs the cause and rethrows a plain RuntimeException('Log folder creation error'), which aborts starting the function instance.

Source

Thrown at pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/process/ProcessRuntime.java:169

    /**
     * The core logic that initialize the process container and executes the function.
     */
    @Override
    public void start() {
        java.lang.Runtime.getRuntime().addShutdownHook(new Thread(() -> process.destroy()));

        // Note: we create the expected log folder before the function process logger attempts to create it
        // This is because if multiple instances are launched they can encounter a race condition creation of the dir.

        log.info().attr("logDir", funcLogDir).log("Creating function log directory");

        try {
            Files.createDirectories(Paths.get(funcLogDir));
        } catch (IOException e) {
            log.info().attr("logDir", funcLogDir).exception(e)
                    .log("Exception when creating log folder");
            throw new RuntimeException("Log folder creation error");
        }

        log.info().attr("logDir", funcLogDir).log("Created or found function log directory");

        startProcess();
        if (channel == null && stub == null) {
            channel = ManagedChannelBuilder.forAddress("127.0.0.1", instancePort)
                    .usePlaintext()
                    .build();
            stub = InstanceControlGrpc.newStub(channel);

            timer = InstanceCache.getInstanceCache().getScheduledExecutorService()
                    .scheduleAtFixedRate(catchingAndLoggingThrowables(() -> {
                        CompletableFuture<HealthCheckResult> result = healthCheck();
                        try {
                            result.get();
                        } catch (Exception e) {
                            log.error().attr("name", instanceConfig.getFunctionDetails().getName())

View on GitHub (pinned to 820761864e)

Solutions

  1. Check the preceding 'Exception when creating log folder' log line for the underlying IOException cause and fix it (permissions, disk space, path).
  2. Ensure the log directory path (and parents) is writable by the user running the function worker.
  3. Verify pulsar.functions.process.container.log.dir points to a directory, not an existing file, and is on a writable volume.
  4. Restart the worker after fixing the environment; the exception is thrown at start time only.

Example fix

# before
$ ls -ld /pulsar/logs  # root-owned, worker runs as pulsar
# after
$ sudo chown -R pulsar:pulsar /pulsar/logs && sudo chmod u+rwx /pulsar/logs
Defensive patterns

Strategy: validation

Validate before calling

Path logDir = Paths.get(funcLogDir);
if (Files.exists(logDir) && !Files.isDirectory(logDir)) {
    throw new IllegalStateException(funcLogDir + " exists but is not a directory");
}
if (!Files.isWritable(logDir.getParent() != null ? logDir.getParent() : logDir)) {
    throw new IllegalStateException("log dir parent not writable: " + logDir.getParent());
}

Try / catch

try {
    runtime.start();
} catch (RuntimeException e) {
    if ("Log folder creation error".equals(e.getMessage())) {
        // inspect the preceding 'Exception when creating log folder' log line, fix perms/disk, retry
    }
    throw e;
}

Prevention

When it happens

Trigger: Starting a ProcessRuntime (local runner / process container) when the configured log directory cannot be created: parent dir not writable, path exists as a regular file, disk full, read-only mount, or invalid path characters/permissions inside the function worker container.

Common situations: pulsar.functions.process.container.log.dir pointing to a non-writable path in the container; running the worker as a non-root user against a root-owned log dir; Kubernetes volume mounted read-only; leftover file occupying the log directory path after a crash.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/be4b3411a129f23e. Report an issue: GitHub.