{"record":{"id":"fa48f9d7dab53e7e","repo":"apache/hadoop","slug":"error-fa48f9","errorCode":null,"errorMessage":"{}","messagePattern":"\\{\\}","errorType":"validation","errorClass":"InvalidPathException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java","lineNumber":2807,"sourceCode":"      builder.append(\"DIR* NameSystem.startFile: src=\").append(src)\n          .append(\", holder=\").append(holder)\n          .append(\", clientMachine=\").append(clientMachine)\n          .append(\", createParent=\").append(createParent)\n          .append(\", replication=\").append(replication)\n          .append(\", createFlag=\").append(flag)\n          .append(\", blockSize=\").append(blockSize)\n          .append(\", supportedVersions=\")\n          .append(Arrays.toString(supportedVersions))\n          .append(\", ecPolicyName=\").append(ecPolicyName)\n          .append(\", storagePolicy=\").append(storagePolicy);\n      NameNode.stateChangeLog.debug(builder.toString());\n    }\n    if (!DFSUtil.isValidName(src) ||\n        FSDirectory.isExactReservedName(src) ||\n        (FSDirectory.isReservedName(src)\n            && !FSDirectory.isReservedRawName(src)\n            && !FSDirectory.isReservedInodesName(src))) {\n      throw new InvalidPathException(src);\n    }\n\n    boolean shouldReplicate = flag.contains(CreateFlag.SHOULD_REPLICATE);\n    if (shouldReplicate &&\n        (!org.apache.commons.lang3.StringUtils.isEmpty(ecPolicyName))) {\n      throw new HadoopIllegalArgumentException(\"SHOULD_REPLICATE flag and \" +\n          \"ecPolicyName are exclusive parameters. Set both is not allowed!\");\n    }\n\n    INodesInPath iip = null;\n    boolean skipSync = true; // until we do something that might create edits\n    HdfsFileStatus stat = null;\n    BlocksMapUpdateInfo toRemoveBlocks = null;\n\n    checkOperation(OperationCategory.WRITE);\n    final FSPermissionChecker pc = getPermissionChecker();\n    writeLock(RwLockMode.FS);\n    try {","sourceCodeStart":2789,"sourceCodeEnd":2825,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSNamesystem.java#L2789-L2825","documentation":"startFile validates the target path before locking: it must pass DFSUtil.isValidName (absolute, no illegal components), must not equal the reserved root exactly, and any /.reserved usage is only allowed for the raw (.reserved/raw) or inodes (.reserved/inodes) virtual namespaces. Anything else throws InvalidPathException echoing the offending src.","triggerScenarios":"DFSClient.create with a relative path (no scheme/authority qualification), a path containing '.' or '..' components, an empty path, or attempts to create directly under /.reserved or an unrecognized /.reserved subtree.","commonSituations":"Apps building paths from raw user input without normalization; forgetting Path.makeQualified so the working-directory-relative string reaches the NN as-is; tooling poking /.reserved virtual namespaces incorrectly.","solutions":["Qualify and normalize client-side: Path p = new Path(raw).makeQualified(fs.getUri(), fs.getWorkingDir()); pass p.toString()","Reject '.'/'..' components at the input boundary — HDFS paths never contain them","For raw block-level access use /.reserved/raw/<realPath>; for inode-id access /.reserved/inodes/<id>; never create under /.reserved itself"],"exampleFix":"// before\nfs.create(new Path(userInput));   // 'file.txt' or 'a/./b' -> InvalidPathException\n// after\nPath p = new Path(userInput).makeQualified(fs.getUri(), fs.getWorkingDir());\nfs.create(p);","handlingStrategy":"validation","validationCode":"Path q = new Path(raw).makeQualified(fs.getUri(), fs.getWorkingDir());\nfor (String comp : q.toUri().getPath().split(\"/\")) {\n  if (comp.equals(\".\") || comp.equals(\"..\")) throw new IllegalArgumentException(\"bad path component: \" + raw);\n}","typeGuard":"static boolean isWritableHdfsName(String src) {\n  if (src == null || !src.startsWith(\"/\")) return false;\n  if (src.equals(\"/.reserved\")) return false;\n  if (src.startsWith(\"/.reserved\")\n      && !(src.startsWith(\"/.reserved/raw/\") || src.startsWith(\"/.reserved/inodes/\"))) return false;\n  for (String c : src.split(\"/\")) { if (c.equals(\".\") || c.equals(\"..\")) return false; }\n  return true;\n}","tryCatchPattern":"catch (InvalidPathException e) { re-prompt for a valid absolute HDFS path; qualify via new Path(input, defaultParent).makeQualified(uri, workingDir) }","preventionTips":["Always makeQualified() paths built from user or config input","Reject '.'/'..' components at the input boundary"],"tags":["hdfs","path-validation","reserved-names","invalid-path","file-create"],"backgroundTag":"invalid-path","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}