{"record":{"id":"708247f658bff984","repo":"eclipse-vertx/vert.x","slug":"failed-to-move-from-to-to","errorCode":null,"errorMessage":"Failed to move ${from} to ${to}","messagePattern":"Failed to move (.+?) to (.+?)","errorType":"exception","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java","lineNumber":487,"sourceCode":"        return null;\n      }\n    };\n  }\n\n  private BlockingAction<Void> moveInternal(String from, String to, CopyOptions options) {\n    Objects.requireNonNull(from);\n    Objects.requireNonNull(to);\n    Objects.requireNonNull(options);\n    Set<CopyOption> copyOptionSet = toCopyOptionSet(options);\n    CopyOption[] copyOptions = copyOptionSet.toArray(new CopyOption[0]);\n    return new BlockingAction<Void>() {\n      public Void perform() {\n        try {\n          Path source = resolveFile(from).toPath();\n          Path target = resolveFile(to).toPath();\n          Files.move(source, target, copyOptions);\n        } catch (IOException e) {\n          throw new FileSystemException(getFileMoveErrorMessage(from, to), e);\n        }\n        return null;\n      }\n    };\n  }\n\n  private BlockingAction<Void> truncateInternal(String p, long len) {\n    Objects.requireNonNull(p);\n    return new BlockingAction<Void>() {\n      public Void perform() {\n        try {\n          String path = resolveFile(p).getAbsolutePath();\n          if (len < 0) {\n            throw new FileSystemException(\"Cannot truncate file to size < 0\");\n          }\n          if (!Files.exists(Paths.get(path))) {\n            throw new FileSystemException(\"Cannot truncate file \" + path + \". Does not exist\");\n          }","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java#L469-L505","documentation":"The blocking move action in FileSystemImpl wraps IOException from java.nio.file.Files.move into FileSystemException 'Failed to move <from> to <to>'. Vert.x throws it when fileSystem().move/moveBlocking cannot rename or relocate the file at the OS level. The cause distinguishes missing source, existing target, or cross-filesystem issues.","triggerScenarios":"vertx.fileSystem().move(from, to) where the source does not exist, the target exists without REPLACE_EXISTING, the target is on a different filesystem without ATOMIC_MOVE compatibility, or the source file is locked/open by another process (notably Windows).","commonSituations":"Moving a log/upload file while it is still being written; rename across mount points (e.g. /tmp to /app on different devices); target filename collision; Windows file locks from scanners or other readers; ATOMIC_MOVE combined with cross-device rename.","solutions":["Check cause: NoSuchFileException -> verify source path; FileAlreadyExistsException -> add REPLACE_EXISTING or delete target first.","For cross-filesystem moves, don't combine with ATOMIC_MOVE (or fall back to copy+delete) since rename(2) fails across devices.","Close all streams/handles reading the source before moving; on Windows ensure antivirus/indexers release the lock.","Create the target parent directory before the move."],"exampleFix":"// before\nvertx.fileSystem().moveBlocking(\"/tmp/upload/f.bin\", \"/data/f.bin\"); // cross-device\n// after: copy then delete\nvertx.fileSystem().copyBlocking(\"/tmp/upload/f.bin\", \"/data/f.bin\");\nvertx.fileSystem().deleteBlocking(\"/tmp/upload/f.bin\");","handlingStrategy":"validation","validationCode":"FileSystem fs = vertx.fileSystem();\nif (!fs.existsBlocking(from)) throw new FileNotFoundException(from);\nif (fs.existsBlocking(to) && !overwrite) throw new FileAlreadyExistsException(to);\nFiles.createDirectories(Paths.get(to).getParent());\nif (Paths.get(from).toFile().getFreeSpace() == 0 ||\n    !Paths.get(from).toFile().equalsSamePathIfAtomic) { /* same-volume check */ }\nif (!Files.isWritable(Paths.get(from).getParent())) throw new AccessDeniedException(from);","typeGuard":"static boolean isRenameable(Path from, Path to, boolean overwrite) {\n  try {\n    boolean sameVolume = Files.getFileStore(from).equals(Files.getFileStore(to.getParent()));\n    return Files.exists(from) && sameVolume && (overwrite || !Files.exists(to));\n  } catch (IOException e) { return false; }\n}","tryCatchPattern":"try {\n  fs.moveBlocking(from, to);\n} catch (FileSystemException e) {\n  if (e.getCause() instanceof AtomicMoveNotSupportedException\n      || e.getCause() instanceof FileSystemException) {\n    fs.copyBlocking(from, to, StandardCopyOption.REPLACE_EXISTING);\n    fs.deleteBlocking(from); // fallback: copy+delete across devices\n  } else throw e;\n}","preventionTips":["Close all readers/writers of the source file before moving (Windows especially)","Check source and target are on the same filesystem if relying on atomic rename","Delete or REPLACE_EXISTING the target before moving","Create the target parent directory first"],"tags":["file-system","move","rename","io"],"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"}