{"record":{"id":"60be489599af6fc6","repo":"eclipse-vertx/vert.x","slug":"failed-to-write-path","errorCode":null,"errorMessage":"Failed to write ${path}","messagePattern":"Failed to write (.+?)","errorType":"exception","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java","lineNumber":883,"sourceCode":"          }\n        } catch (IOException e) {\n          throw new FileSystemException(getFileAccessErrorMessage(\"read\", path), e);\n        }\n      }\n    };\n  }\n\n  private BlockingAction<Void> writeFileInternal(String path, Buffer data) {\n    Objects.requireNonNull(path);\n    Objects.requireNonNull(data);\n    return new BlockingAction<Void>() {\n      public Void perform() {\n        try {\n          Path target = resolveFile(path).toPath();\n          Files.write(target, data.getBytes());\n          return null;\n        } catch (IOException e) {\n          throw new FileSystemException(getFileAccessErrorMessage(\"write\", path), e);\n        }\n      }\n    };\n  }\n\n  private BlockingAction<AsyncFile> openInternal(String p, OpenOptions options) {\n    Objects.requireNonNull(p);\n    Objects.requireNonNull(options);\n    return new BlockingAction<AsyncFile>() {\n      public AsyncFile perform() {\n        String path = resolveFile(p).getAbsolutePath();\n        return doOpen(path, options, context);\n      }\n    };\n  }\n\n  protected AsyncFile doOpen(String path, OpenOptions options, ContextInternal context) {\n    return new AsyncFileImpl(vertx, path, options, context);","sourceCodeStart":865,"sourceCodeEnd":901,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java#L865-L901","documentation":"Wrapped error in writeFileInternal: Files.write to the resolved target path threw an IOException. The message names the write operation and the raw path; the underlying cause (no such parent directory, permission denied, disk full) is attached.","triggerScenarios":"Calling FileSystem.writeFile(path, buffer) when the parent directory does not exist, the process lacks write permission, the target is a directory, or the disk is full.","commonSituations":"Writing to /etc or other root-owned paths from a non-root service, forgetting to create the output directory first, or read-only container filesystems.","solutions":["Create parent directories before writing (fs.mkdirs)","Inspect the cause for permission or space issues","Verify the target path is writable"],"exampleFix":"// before\nvertx.fileSystem().writeFile(\"out/result.json\", buffer);\n// after\nvertx.fileSystem().mkdirs(\"out\")\n  .compose(v -> vertx.fileSystem().writeFile(\"out/result.json\", buffer));","handlingStrategy":"try-catch","validationCode":"Path target = Path.of(path);\nif (!Files.isDirectory(target.getParent()) || !Files.isWritable(target.getParent())) {\n  throw new IllegalStateException(\"Cannot write to: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n  fs.writeFile(path, data);\n} catch (FileSystemException e) {\n  logger.error(\"Write failed for {}: {}\", path, e.getCause());\n  // create dirs / fix permissions / free disk, then retry\n}","preventionTips":["Create parent directories with mkdirs before writing","Verify write permission for the service user","Check free disk space and that the filesystem is not read-only"],"tags":["filesystem","io","write"],"backgroundTag":"file-write-failed","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"}