{"record":{"id":"7c9635278dc18520","repo":"eclipse-vertx/vert.x","slug":"failed-to-create-path","errorCode":null,"errorMessage":"Failed to create ${path}","messagePattern":"Failed to create (.+?)","errorType":"exception","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java","lineNumber":737,"sourceCode":"    return new BlockingAction<Void>() {\n      public Void perform() {\n        try {\n          Path source = resolveFile(path).toPath();\n          if (createParents) {\n            if (attrs != null) {\n              Files.createDirectories(source, attrs);\n            } else {\n              Files.createDirectories(source);\n            }\n          } else {\n            if (attrs != null) {\n              Files.createDirectory(source, attrs);\n            } else {\n              Files.createDirectory(source);\n            }\n          }\n        } catch (IOException e) {\n          throw new FileSystemException(getFolderAccessErrorMessage(\"create\", path), e);\n        }\n        return null;\n      }\n    };\n  }\n\n  protected BlockingAction<String> createTempDirectoryInternal(String parentDir, String prefix, String perms) {\n    FileAttribute<?> attrs = perms == null ? null : PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString(perms));\n    return new BlockingAction<String>() {\n      public String perform() {\n        try {\n          Path tmpDir;\n          if (parentDir != null) {\n            Path dir = resolveFile(parentDir).toPath();\n            if (attrs != null) {\n              tmpDir = Files.createTempDirectory(dir, prefix, attrs);\n            } else {\n              tmpDir = Files.createTempDirectory(dir, prefix);","sourceCodeStart":719,"sourceCodeEnd":755,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java#L719-L755","documentation":"Thrown when FileSystem.mkdir / mkdirs fails: Vert.x calls Files.createDirectory (with POSIX attrs when perms are given) and wraps any IOException into a FileSystemException via getFolderAccessErrorMessage(\"create\", path) — 'Failed to create <path>'. Note mkdir (not mkdirs) fails if a parent directory is missing or the directory already exists.","triggerScenarios":"vertx.fileSystem().mkdir(path) or mkdir(path, perms) when the parent directory does not exist, the directory already exists (FileAlreadyExistsException), or the parent is not writable.","commonSituations":"Creating a deeply nested path with mkdir instead of mkdirs; output directories that already exist from a previous run; read-only volume or missing write permission in containers.","solutions":["Use mkdirs/mkdirsBlocking to create all missing parent directories.","Check existsBlocking(path) first, or treat FileAlreadyExistsException in the cause as success.","Verify write permission on the parent directory.","Pass valid POSIX perms string if using the perms overload (e.g. \"rwxr-x---\")."],"exampleFix":"// before\nvertx.fileSystem().mkdirBlocking(\"/app/data/cache/v2\"); // parent missing\n// after\nvertx.fileSystem().mkdirsBlocking(\"/app/data/cache/v2\");","handlingStrategy":"validation","validationCode":"FileSystem fs = vertx.fileSystem();\nif (!fs.existsBlocking(path)) fs.mkdirsBlocking(path, perms); // idempotent create","typeGuard":null,"tryCatchPattern":"try { vertx.fileSystem().mkdirBlocking(path, perms); } catch (FileSystemException e) { if (e.getCause() instanceof FileAlreadyExistsException) { /* ok */ } else throw e; }","preventionTips":["Prefer mkdirs for nested paths","Treat already-exists as success in idempotent setup code","Check write permission on the parent directory","Validate perms strings are valid POSIX notation"],"tags":["filesystem","mkdir","directory","io"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}