{"record":{"id":"823f78094dce1715","repo":"apache/beam","slug":"unable-to-rename-resource-s-to-s-no-further-information","errorCode":null,"errorMessage":"Unable to rename resource %s to %s. No further information provided by underlying filesystem.","messagePattern":"Unable to rename resource (.+?) to (.+?)\\. No further information provided by underlying filesystem\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/hadoop-file-system/src/main/java/org/apache/beam/sdk/io/hdfs/HadoopFileSystem.java","lineNumber":291,"sourceCode":"        LOG.debug(LOG_DELETING_EXISTING_FILE, Path.getPathWithoutSchemeAndAuthority(destPath));\n        fs.delete(destPath, false); // not recursive\n        success = fs.rename(srcPath, destPath);\n      }\n\n      if (!success) {\n        if (!fs.exists(srcPath)) {\n          throw new FileNotFoundException(\n              String.format(\n                  \"Unable to rename resource %s to %s as source not found.\", srcPath, destPath));\n\n        } else if (fs.exists(destPath)) {\n          throw new FileAlreadyExistsException(\n              String.format(\n                  \"Unable to rename resource %s to %s as destination already exists and couldn't be deleted.\",\n                  srcPath, destPath));\n\n        } else {\n          throw new IOException(\n              String.format(\n                  \"Unable to rename resource %s to %s. No further information provided by underlying filesystem.\",\n                  srcPath, destPath));\n        }\n      }\n    }\n  }\n\n  /** Ensures that the target directory exists for the given filePath. */\n  private void mkdirs(Path filePath) throws IOException {\n    final org.apache.hadoop.fs.FileSystem fs = filePath.getFileSystem(configuration);\n    final Path targetDirectory = filePath.getParent();\n    if (!fs.exists(targetDirectory)) {\n      LOG.debug(LOG_CREATE_DIRECTORY, Path.getPathWithoutSchemeAndAuthority(targetDirectory));\n      if (!fs.mkdirs(targetDirectory)) {\n        throw new IOException(\n            String.format(\n                \"Unable to create target directory %s. No further information provided by underlying filesystem.\",","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/hadoop-file-system/src/main/java/org/apache/beam/sdk/io/hdfs/HadoopFileSystem.java#L273-L309","documentation":"The catch-all branch of HadoopFileSystem.rename(): when fs.rename() returns false, the source exists, and the destination does not exist, Beam has no diagnosis and throws a generic IOException stating the underlying filesystem provided no further information.","triggerScenarios":"Calling HadoopFileSystem.rename() where fs.rename() returns false with srcPath existing and destPath not existing — e.g. transient NameNode/RPC failures, path-level permission errors on the rename itself, or跨 filesystem moves.","commonSituations":"HDFS in safe mode, insufficient permission on the source's parent directory, or attempting to rename across different filesystems (e.g. hdfs:// to file://).","solutions":["Check NameNode health / safe-mode status and retry the rename.","Verify write permission on the source's parent directory (rename requires it).","Ensure src and dest share the same filesystem scheme; copy+delete instead if not.","Inspect Hadoop client and NameNode logs for the suppressed cause."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Verify same filesystem scheme and parent write access before rename\nif (!src.getScheme().equals(dest.getScheme())) {\n  throw new IllegalArgumentException(\"Cross-filesystem rename not supported\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  fileSystem.rename(srcs, dests);\n} catch (IOException e) {\n  // retry with backoff; check NameNode safe mode / permissions in logs\n  retryWithBackoff(() -> fileSystem.rename(srcs, dests));\n}","preventionTips":["Retry transient rename failures with backoff","Confirm src and dest are on the same filesystem","Check NameNode safe mode and parent-directory permissions"],"tags":["hadoop","hdfs","rename","beam"],"backgroundTag":"file-write-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}