{"record":{"id":"cc40fffe42f6de26","repo":"apache/hadoop","slug":"unexpected-file-in-store-dir","errorCode":null,"errorMessage":"Unexpected file in store: ${dir}","messagePattern":"Unexpected file in store: (.+?)","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-hs/src/main/java/org/apache/hadoop/mapreduce/v2/hs/HistoryServerFileSystemStateStoreService.java","lineNumber":232,"sourceCode":"    return tokenId.getSequenceNumber() % NUM_TOKEN_BUCKETS;\n  }\n\n  private Path getTokenBucketPath(int bucketId) {\n    return new Path(tokenStatePath,\n        String.format(TOKEN_BUCKET_NAME_FORMAT, bucketId));\n  }\n\n  private Path getTokenPath(MRDelegationTokenIdentifier tokenId) {\n    Path bucketPath = getTokenBucketPath(getBucketId(tokenId));\n    return new Path(bucketPath,\n        TOKEN_FILE_PREFIX + tokenId.getSequenceNumber());\n  }\n\n  private void createDir(Path dir) throws IOException {\n    try {\n      FileStatus status = fs.getFileStatus(dir);\n      if (!status.isDirectory()) {\n        throw new FileAlreadyExistsException(\"Unexpected file in store: \"\n            + dir);\n      }\n      if (!status.getPermission().equals(DIR_PERMISSIONS)) {\n        fs.setPermission(dir, DIR_PERMISSIONS);\n      }\n    } catch (FileNotFoundException e) {\n      fs.mkdirs(dir, DIR_PERMISSIONS);\n    }\n  }\n\n  private void createNewFile(Path file, byte[] data)\n      throws IOException {\n    Path tmp = new Path(file.getParent(), TMP_FILE_PREFIX + file.getName());\n    writeFile(tmp, data);\n    try {\n      if (!fs.rename(tmp, file)) {\n        throw new IOException(\"Could not rename \" + tmp + \" to \" + file);\n      }","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-hs/src/main/java/org/apache/hadoop/mapreduce/v2/hs/HistoryServerFileSystemStateStoreService.java#L214-L250","documentation":"During state-store initialization the service creates its directory layout (root, keys directory, token bucket directories). createDir expects any pre-existing path to be a directory; if getFileStatus reports a regular file, it throws FileAlreadyExistsException 'Unexpected file in store'. The configured store location is occupied by a file where the store must create and own a directory.","triggerScenarios":"mapreduce.jobhistory.recovery.store.fs.uri points at a path occupied by a plain file; a file (not a directory) named like the keys or a bucket directory exists inside the store tree; provisioning scripts created a marker file instead of a directory.","commonSituations":"Store URI typo resolving to a file; artifact copy or touch commands run inside the store path; manual manipulation of the store tree.","solutions":["Inspect the reported path: hadoop fs -ls on its parent to see the offending file.","Remove or relocate the file.","Re-point the store URI to an empty dedicated directory and restart JHS."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# verify the store root is a directory and its parent is writable before JHS start\nhadoop fs -test -d /jhs-state || hadoop fs -mkdir -p /jhs-state\nhadoop fs -test -w / || echo 'parent not writable'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Provision the store path as an empty dedicated directory.","Do not place marker files or artifacts inside the recovery store tree.","Validate the store URI in deployment scripts before starting JHS."],"tags":["mapreduce","job-history-server","state-store","filesystem","initialization"],"backgroundTag":"path-is-file-not-directory","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}