{"record":{"id":"6ae038e28cf56a1f","repo":"apache/hadoop","slug":"only-hdfs-is-supported-as-underlyingfilesystem-fs","errorCode":null,"errorMessage":"Only HDFS is supported as underlyingFileSystem, fs scheme:{} uri to be added{}","messagePattern":"Only HDFS is supported as underlyingFileSystem, fs scheme:(.+?) uri to be added(.+?)","errorType":"exception","errorClass":"FileSystemException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-nfs/src/main/java/org/apache/hadoop/hdfs/nfs/nfs3/Nfs3Utils.java","lineNumber":268,"sourceCode":"    URI fsURI = fs.getUri();\n    String scheme = fs.getScheme();\n    if (scheme.equalsIgnoreCase(FsConstants.VIEWFS_SCHEME)) {\n      ViewFileSystem viewFs = (ViewFileSystem)fs;\n      ViewFileSystem.MountPoint[] mountPoints = viewFs.getMountPoints();\n      for (ViewFileSystem.MountPoint mount : mountPoints) {\n        String mountedPath = mount.getMountedOnPath().toString();\n        if (exportPath.startsWith(mountedPath)) {\n          String subpath = exportPath.substring(mountedPath.length());\n          fsURI = mount.getTargetFileSystemURIs()[0].resolve(subpath);\n          break;\n        }\n      }\n    } else if (scheme.equalsIgnoreCase(HdfsConstants.HDFS_URI_SCHEME)) {\n      fsURI = fsURI.resolve(exportPath);\n    }\n\n    if (!fsURI.getScheme().equalsIgnoreCase(HdfsConstants.HDFS_URI_SCHEME)) {\n      throw new FileSystemException(\"Only HDFS is supported as underlying\"\n          + \"FileSystem, fs scheme:\" + scheme + \" uri to be added\" + fsURI);\n    }\n    return fsURI;\n  }\n}\n","sourceCodeStart":250,"sourceCodeEnd":274,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-nfs/src/main/java/org/apache/hadoop/hdfs/nfs/nfs3/Nfs3Utils.java#L250-L274","documentation":"Nfs3Utils resolves the backing FileSystem URI for an export (including through mount-table entries) and then enforces that the final scheme is hdfs: the NFS gateway can only re-export HDFS. Any other scheme (file, s3a, viewfs-to-non-hdfs target, etc.) throws this FileSystemException during export registration.","triggerScenarios":"An nfs.exports entry whose URI scheme is not hdfs://; a viewfs mount whose target file system resolves to a non-HDFS URI; a URI with no scheme that defaults to the local filesystem ('file'). The message prints the offending scheme and resolved URI.","commonSituations":"Trying to NFS-export a local directory or object-store path; using defaultFS-less relative export paths; mount-table entries added for non-HDFS backends that the gateway then tries to register.","solutions":["Change the export entry to an explicit hdfs:// URI (hdfs://nameservice/path or hdfs://nn:8020/path).","If using viewfs, fix the mount table so every target that gets exported resolves to an hdfs authority.","Remove non-HDFS paths from nfs.exports — they cannot be served by this gateway."],"exampleFix":"# before (nfs.exports)\n/data rw              # resolves to file:///data via local defaultFS\n# after\n/data hdfs://ns1/data rw   # or set fs.defaultFS to the HDFS nameservice","handlingStrategy":"validation","validationCode":"/* validate the export URI scheme before registration */\nURI u = URI.create(exportUri);\nif (u.getScheme() == null || !u.getScheme().equalsIgnoreCase(\"hdfs\")) {\n    throw new IllegalArgumentException(\n        \"nfs.exports entry must use the hdfs scheme: \" + exportUri);\n}","typeGuard":"private boolean isHdfsExportUri(URI u) {\n    return u != null && \"hdfs\".equalsIgnoreCase(u.getScheme());\n}","tryCatchPattern":"try {\n    URI backing = Nfs3Utils.getWanRpcAddress... /* resolve export URI */;\n} catch (FileSystemException e) {\n    // deterministic: the message prints the offending scheme and URI.\n    // Fail the export/config check at deploy time; do not retry.\n}","preventionTips":["Write nfs.exports entries with explicit hdfs:// URIs (hdfs://nameservice/path).","Set fs.defaultFS to the HDFS nameservice so scheme-less export paths cannot default to file://.","If viewfs is in play, verify every mount-table target backing an export resolves to an hdfs authority.","Add a startup lint that rejects non-hdfs export entries with a clear message."],"tags":["nfs-gateway","hdfs","filesystem-scheme","exports","configuration"],"backgroundTag":"unsupported-filesystem-scheme","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}