{"record":{"id":"5c2bbb752a7b7f7a","repo":"apache/hadoop","slug":"h03","errorCode":"H03","errorMessage":"FileSystemExecutor error, {0}","messagePattern":"FileSystemExecutor error, (.+?)","errorType":"error_code","errorClass":"FileSystemAccessException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java","lineNumber":370,"sourceCode":"        public T run() throws Exception {\n          FileSystem fs = createFileSystem(conf);\n          Instrumentation instrumentation = getServer().get(Instrumentation.class);\n          Instrumentation.Cron cron = instrumentation.createCron();\n          try {\n            checkNameNodeHealth(fs);\n            cron.start();\n            return executor.execute(fs);\n          } finally {\n            cron.stop();\n            instrumentation.addCron(INSTRUMENTATION_GROUP, executor.getClass().getSimpleName(), cron);\n            closeFileSystem(fs);\n          }\n        }\n      });\n    } catch (FileSystemAccessException ex) {\n      throw ex;\n    } catch (Exception ex) {\n      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H03, ex);\n    }\n  }\n\n  public FileSystem createFileSystemInternal(String user, final Configuration conf)\n    throws IOException, FileSystemAccessException {\n    Check.notEmpty(user, \"user\");\n    Check.notNull(conf, \"conf\");\n    if (!conf.getBoolean(FILE_SYSTEM_SERVICE_CREATED, false)) {\n      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H04);\n    }\n    try {\n      validateNamenode(\n          new URI(conf.getTrimmed(\n              CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY)).\n                  getAuthority());\n      UserGroupInformation ugi = getUGI(user);\n      return ugi.doAs(new PrivilegedExceptionAction<FileSystem>() {\n        @Override","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java#L352-L388","documentation":"FileSystemAccessService.execute() runs a FileSystemExecutor inside a UserGroupInformation.doAs with a filesystem obtained from the service cache; any exception that is not itself a FileSystemAccessException - typically an IOException from the HDFS operation - is wrapped as error H03 ('FileSystemExecutor error') with the original exception as parameter {0} and cause. This is the generic failure surface for every httpfs filesystem operation.","triggerScenarios":"Calling FileSystemAccess.execute(user, conf, executor) where executor.execute(fs) (or the cached-filesystem acquisition/creation inside the action) throws: FileNotFoundException on a missing path, AccessControlException for permissions, RecoverableException/standby NameNode errors, checksum or quota failures, etc.","commonSituations":"Httpfs REST call on a deleted path; proxy-user (doAs) lacks HDFS permissions; NameNode in safe mode or standby; any HDFS client-level IOException surfacing through httpfs as a 400/exception response.","solutions":["Unwrap the cause: H03 carries the real exception - read its type/message (FileNotFoundException, AccessControlException, ...) and fix that underlying problem","Verify the path exists and the effective (doAs) user has permissions","Check NameNode health/safe mode and that the correct active NameNode is addressed","For transient causes (standby switch, safe mode), retry after resolving the cluster state"],"exampleFix":"// before\nFileSystemAccess fsAccess = ...;\nfsAccess.execute(\"alice\", conf, executor); // H03 wraps FileNotFoundException\n\n// after: fix the underlying cause (path existed only under a different user)\nfsAccess.execute(\"hdfs\", conf, executor);","handlingStrategy":"try-catch","validationCode":"// Pre-flight the operation's target when possible\nif (executor instanceof PathAware) {\n  Path p = ((PathAware) executor).getPath();\n  // let callers verify existence/permissions cheaply before execute()\n  // (existence check is best-effort; HDFS is the source of truth)\n}","typeGuard":null,"tryCatchPattern":"try {\n  return fsAccess.execute(user, conf, executor);\n} catch (FileSystemAccessException ex) {\n  if (ex.getError() == FileSystemAccessException.ERROR.H03) {\n    Throwable cause = ex.getCause();\n    if (cause instanceof java.io.FileNotFoundException) { /* map to 404 */ }\n    else if (cause instanceof org.apache.hadoop.security.AccessControlException) { /* map to 403 */ }\n    else { /* map to 500, include cause message */ }\n  }\n  throw ex;\n}","preventionTips":["Map H03's cause to precise HTTP status codes instead of returning a generic error","Validate user-supplied paths (no traversal, correct scheme) before executing","Handle transient causes (standby NN, safe mode) with a bounded retry, permanent ones (missing file, permissions) without","Log cause, not just the wrapper, so incidents are diagnosable"],"tags":["httpfs","hdfs","filesystem","io","wrapper"],"backgroundTag":"hdfs-operation-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}