{"record":{"id":"09f7afcbd2896882","repo":"apache/hadoop","slug":"couldn-t-obtain-an-instance-of-rawlocalfilesystem","errorCode":null,"errorMessage":"Couldn't obtain an instance of RawLocalFileSystem.","messagePattern":"Couldn't obtain an instance of RawLocalFileSystem\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/SecureIOUtils.java","lineNumber":80,"sourceCode":"   *\n   * If security is enabled but the support code is unavailable, throws a\n   * RuntimeException since we don't want to run insecurely.\n   */\n  static {\n    boolean shouldBeSecure = UserGroupInformation.isSecurityEnabled();\n    boolean canBeSecure = NativeIO.isAvailable();\n\n    if (!canBeSecure && shouldBeSecure) {\n      throw new RuntimeException(\n        \"Secure IO is not possible without native code extensions.\");\n    }\n\n    // Pre-cache an instance of the raw FileSystem since we sometimes\n    // do secure IO in a shutdown hook, where this call could fail.\n    try {\n      rawFilesystem = FileSystem.getLocal(new Configuration()).getRaw();\n    } catch (IOException ie) {\n      throw new RuntimeException(\n      \"Couldn't obtain an instance of RawLocalFileSystem.\");\n    }\n\n    // SecureIO just skips security checks in the case that security is\n    // disabled\n    skipSecurity = !canBeSecure;\n  }\n\n  private final static boolean skipSecurity;\n  private final static FileSystem rawFilesystem;\n\n  /**\n   * @return Open the given File for random read access, verifying the expected user/\n   * group constraints if security is enabled.\n   * \n   * Note that this function provides no additional security checks if hadoop\n   * security is disabled, since doing the checks would be too expensive when\n   * native libraries are not available.","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/SecureIOUtils.java#L62-L98","documentation":"Thrown from SecureIOUtils' static initializer when FileSystem.getLocal(new Configuration()) throws while pre-caching a RawLocalFileSystem. The instance is cached eagerly because secure I/O sometimes runs in shutdown hooks where filesystem lookup would fail. Like the sibling security error, it surfaces as ExceptionInInitializerError wrapping this RuntimeException on first use of the class.","triggerScenarios":"Class initialization in a JVM whose configuration makes local filesystem creation throw IOException: fs.file.impl / fs.raw-file-system.impl set to a class that is not on the classpath or fails to construct, core-site.xml unreadable or syntactically broken, or the FileSystem cache already closed (FileSystem.closeAll()) before first use.","commonSituations":"Custom fs.file.impl overrides left in core-site.xml after a jar upgrade; shaded/relocated fat jars breaking FileSystem service loading; embedded apps that call FileSystem.closeAllForUGI and later touch SecureIOUtils; containers missing HADOOP_CONF_DIR so Configuration loads no valid local fs binding.","solutions":["Reproduce the root cause in a scratch program: FileSystem.getLocal(new Configuration()).getRaw() and read the underlying IOException stack","Verify core-site.xml on the classpath is valid XML and remove stale fs.file.impl / fs.raw-file-system.impl overrides","Ensure hadoop-common jar and etc/hadoop config dir are both on the client classpath","If your code closes the FileSystem cache, do it only after all SecureIOUtils work is done"],"exampleFix":"// before: bad fs.file.impl in core-site.xml -> ExceptionInInitializerError at class load\nSecureIOUtils.createForWrite(f, 0644);\n\n// after: startup smoke test that surfaces the real IOException\nFileSystem local = FileSystem.getLocal(new Configuration()).getRaw(); // fails loudly at deploy time\nLOG.info(\"local fs ok: {}\", local.getUri());","handlingStrategy":"validation","validationCode":"// startup smoke test: if this throws, SecureIOUtils class init will too\nFileSystem raw = FileSystem.getLocal(new Configuration()).getRaw();\nLOG.info(\"RawLocalFileSystem ok: {}\", raw.getUri());","typeGuard":null,"tryCatchPattern":"try {\n  SecureIOUtils.openForRead(f, owner);\n} catch (ExceptionInInitializerError e) {\n  Throwable cause = e.getCause(); // RuntimeException with the real message\n  if (cause != null && cause.getMessage().contains(\"RawLocalFileSystem\")) {\n    // local filesystem config problem, not the native-library problem\n  }\n  throw e;\n}","preventionTips":["Keep a canary check that constructs FileSystem.getLocal(conf) in application health checks","Review fs.file.impl / fs.raw-file-system.impl overrides whenever hadoop jars are upgraded","Never call FileSystem.closeAll() while secure IO paths may still be used later in the JVM"],"tags":["hadoop","filesystem","static-initializer","configuration"],"backgroundTag":"local-filesystem-misconfigured","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}