{"record":{"id":"1165ff5a650521f9","repo":"apache/pulsar","slug":"dir-could-not-be-created","errorCode":null,"errorMessage":"${dir} could not be created","messagePattern":"(.+?) could not be created","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/nar/FileUtils.java","lineNumber":85,"sourceCode":"\n            while (read > -1) {\n                digest.update(buffer, 0, read);\n                read = inputStream.read(buffer);\n            }\n\n            return digest.digest();\n        } catch (NoSuchAlgorithmException nsae) {\n            throw new IllegalArgumentException(nsae);\n        }\n    }\n\n    public static void ensureDirectoryExistAndCanReadAndWrite(final File dir) throws IOException {\n        if (dir.exists() && !dir.isDirectory()) {\n            throw new IOException(dir.getAbsolutePath() + \" is not a directory\");\n        } else if (!dir.exists()) {\n            final boolean made = dir.mkdirs();\n            if (!made) {\n                throw new IOException(dir.getAbsolutePath() + \" could not be created\");\n            }\n        }\n        if (!(dir.canRead() && dir.canWrite())) {\n            throw new IOException(dir.getAbsolutePath() + \" directory does not have read/write privilege\");\n        }\n    }\n\n    public static void ensureDirectoryExistAndCanRead(final File dir) throws IOException {\n        if (dir.exists() && !dir.isDirectory()) {\n            throw new IOException(dir.getAbsolutePath() + \" is not a directory\");\n        } else if (!dir.exists()) {\n            final boolean made = dir.mkdirs();\n            if (!made) {\n                throw new IOException(dir.getAbsolutePath() + \" could not be created\");\n            }\n        }\n        if (!dir.canRead()) {\n            throw new IOException(dir.getAbsolutePath() + \" directory does not have read privilege\");","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/nar/FileUtils.java#L67-L103","documentation":"In ensureDirectoryExistAndCanReadAndWrite, when the target directory does not exist the code calls File.mkdirs(); if that returns false (and the directory still does not exist) it throws IOException '<abs path> could not be created'. mkdirs fails when a parent is not writable, the path is a dangling symlink, or an OS-level error (permissions, disk full, name too long) prevents creation.","triggerScenarios":"Calling ensureDirectoryExistAndCanReadAndWrite on a non-existent path whose parent chain cannot be created by the current user, e.g. /var/lib/pulsar-nar under a root-only parent.","commonSituations":"See trigger scenarios.","solutions":["Run mkdir -p on the path manually as the service user to reveal the OS error.","Grant the process user write permission on the parent directory (chown/chmod).","Point the configuration at a writable location (e.g. under the process's home or a writable volume).","Check for a dangling symlink at the path and remove it."],"exampleFix":"// before (service user cannot write /var/run)\nFile dir = new File(\"/var/run/pulsar/nar\");\nFileUtils.ensureDirectoryExistAndCanReadAndWrite(dir);\n// after\nFile dir = new File(\"/home/pulsar/run/nar\"); // writable location\nFileUtils.ensureDirectoryExistAndCanReadAndWrite(dir);","handlingStrategy":"try-catch","validationCode":"File parent = dir.getParentFile();\nif (parent != null && !parent.canWrite() && !dir.exists()) {\n    throw new IllegalStateException(\"Parent not writable: \" + parent);\n}","typeGuard":null,"tryCatchPattern":"try {\n    FileUtils.ensureDirectoryExistAndCanReadAndWrite(dir);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"could not be created\")) {\n        // surface OS detail: attempt mkdirs yourself and log errno/permission state\n        log.error(\"Cannot create {}: parent={}, canWrite={}\", dir, dir.getParentFile(),\n            dir.getParentFile() != null && dir.getParentFile().canWrite());\n    }\n    throw e;\n}","preventionTips":["Provision all configured directories in deployment scripts (systemd ExecStartPre / entrypoint) as the service user","Never run the service as root then restart as non-root on the same dirs","Verify writable paths in a startup health check"],"tags":["filesystem","io","permissions","mkdirs"],"backgroundTag":"directory-creation-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}