{"record":{"id":"e6867aaa307ef007","repo":"apache/pulsar","slug":"failed-to-create-base-storage-directory-at-stora","errorCode":null,"errorMessage":"Failed to create base storage directory at ${storagePath}","messagePattern":"Failed to create base storage directory at (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-package-management/filesystem-storage/src/main/java/org/apache/pulsar/packages/management/storage/filesystem/FileSystemPackagesStorage.java","lineNumber":82,"sourceCode":"\n        // Ensure the normalized path is still within the storagePath\n        if (!f.getAbsolutePath().startsWith(storagePath.getAbsolutePath())) {\n            throw new IOException(\"Invalid path: \" + path);\n        }\n\n        if (!f.getParentFile().exists()) {\n            if (!f.getParentFile().mkdirs()) {\n                throw new RuntimeException(\"Failed to create parent dirs for \" + path);\n            }\n        }\n        return f;\n    }\n\n    @Override\n    public void initialize() {\n        if (!storagePath.exists()) {\n            if (!storagePath.mkdirs()) {\n                throw new RuntimeException(\"Failed to create base storage directory at \" + storagePath);\n            }\n        }\n\n        log.info().attr(\"storagePath\", storagePath).log(\"Packages management filesystem storage initialized\");\n    }\n\n    @Override\n    public CompletableFuture<Void> writeAsync(String path, InputStream inputStream) {\n        try {\n            File f = getPath(path);\n\n            @Cleanup\n            OutputStream os = new FileOutputStream(f);\n\n            @Cleanup\n            BufferedOutputStream bos = new BufferedOutputStream(os);\n            ByteStreams.copy(inputStream, bos);\n","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-package-management/filesystem-storage/src/main/java/org/apache/pulsar/packages/management/storage/filesystem/FileSystemPackagesStorage.java#L64-L100","documentation":"At startup, FileSystemPackagesStorage.initialize() creates the configured base storage directory if it does not exist; when storagePath.mkdirs() fails, a RuntimeException naming the path is thrown, aborting initialization. The broker cannot start filesystem package storage without a usable base directory.","triggerScenarios":"initialize() with storagePath pointing to a non-existent directory that cannot be created: parent directories missing and uncreatable, permission denied, read-only filesystem, or storagePath exists as a regular file... (note: if it exists as a file, mkdirs is skipped and other operations will fail).","commonSituations":"Wrong packagesManagement storage path in configuration (typo, unwritable location); container running as non-root without volume permissions; Kubernetes PVC mounted read-only; parent of storagePath not existing.","solutions":["Check permissions on the parent of the configured storage path and grant the broker process user write access.","Pre-create the storage directory manually with correct ownership, then restart.","Verify the volume/mount is writable (not read-only) and the path is correct in configuration.","Ensure storagePath is a directory, not an existing regular file."],"exampleFix":"// before: path not writable\n-DpackagesManagement.storage.filesystem.root=/root/only/packages\n// after\n-DpackagesManagement.storage.filesystem.root=/var/lib/pulsar/packages\n# chown pulsar:pulsar /var/lib/pulsar/packages","handlingStrategy":"validation","validationCode":"java.io.File root = new java.io.File(storageRoot);\nif (!root.exists() && !root.getParentFile().canWrite()) {\n    throw new IllegalStateException(\"Cannot create storage root \" + storageRoot + \": parent not writable\");\n}\nif (root.exists() && !root.isDirectory()) {\n    throw new IllegalStateException(storageRoot + \" exists but is not a directory\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    storage.initialize();\n} catch (RuntimeException e) {\n    if (e.getMessage().startsWith(\"Failed to create base storage directory\")) {\n        log.error(\"Fix storage root permissions/mount: {}\", e.getMessage());\n        throw e; // non-recoverable at startup\n    }\n    throw e;\n}","preventionTips":["Verify storage path permissions in deployment scripts before broker start.","Mount the storage volume read-write (check PVC/K8s volume settings).","Pre-create the storage root with correct ownership via init containers.","Confirm the configured path is a directory, not an existing file."],"tags":["filesystem","io","permissions","startup","storage"],"backgroundTag":"mkdir-failed-permission-denied","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}