{"record":{"id":"6e74ac6297896583","repo":"apache/hadoop","slug":"error-connecting-to-file-system-basepath-ex","errorCode":null,"errorMessage":"Error connecting to file system: ${basePath} [${ex}]","messagePattern":"Error connecting to file system: (.+?) \\[(.+?)\\]","errorType":"exception","errorClass":"MetricsException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/sink/RollingFileSystemSink.java","lineNumber":470,"sourceCode":"   * Return the supplied file system for testing or otherwise get a new file\n   * system.\n   *\n   * @return the file system to use\n   * @throws MetricsException thrown if the file system could not be retrieved\n   */\n  private FileSystem getFileSystem() throws MetricsException {\n    FileSystem fs = null;\n\n    if (suppliedFilesystem != null) {\n      fs = suppliedFilesystem;\n    } else {\n      try {\n        fs = FileSystem.get(new URI(basePath.toString()), conf);\n      } catch (URISyntaxException ex) {\n        throw new MetricsException(\"The supplied filesystem base path URI\"\n            + \" is not a valid URI: \" + basePath.toString(), ex);\n      } catch (IOException ex) {\n        throw new MetricsException(\"Error connecting to file system: \"\n            + basePath + \" [\" + ex.toString() + \"]\", ex);\n      }\n    }\n\n    return fs;\n  }\n\n  /**\n   * Test whether the file system supports append and return the answer.\n   *\n   * @param fs the target file system\n   */\n  private boolean checkAppend(FileSystem fs) {\n    boolean canAppend = true;\n\n    try {\n      fs.append(basePath);\n    } catch (UnsupportedOperationException ex) {","sourceCodeStart":452,"sourceCodeEnd":488,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/sink/RollingFileSystemSink.java#L452-L488","documentation":"getFileSystem() calls FileSystem.get(new URI(basePath), conf); an IOException from that call — resolving or contacting the target filesystem — is wrapped as MetricsException(\"Error connecting to file system: <basePath> [<cause>]\") with the basepath and original exception embedded. This runs once at sink init, so a failed connection means the daemon starts without the rolling metrics sink.","triggerScenarios":"HDFS NameNode unreachable (RPC connection refused/timeout) when the daemon initializes the sink; basepath scheme naming an HA nameservice whose addresses are missing or wrong in the configuration; DNS failure for the NameNode host.","commonSituations":"Daemons starting before HDFS is fully up; fs.defaultFS or nameservice RPC addresses misconfigured; DNS outages in containers.","solutions":["Verify the filesystem is reachable as the daemon user: hdfs dfs -ls <basepath>","Fix fs.defaultFS / dfs.nameservices / HA RPC address configuration for the scheme used in basepath","Restart the daemon after HDFS recovers — this connection is attempted only at initialization","Check the bracketed cause in the message; it distinguishes DNS, timeout and refusal"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"FileSystem fs = FileSystem.get(new URI(basePath.toString()), conf);\nfs.exists(basePath); // forces connection now, surfacing IOException before the daemon relies on the sink","typeGuard":null,"tryCatchPattern":"try {\n  sink.init(subsetConf);\n} catch (MetricsException e) {\n  // message embeds basePath and the original IOException (NN unreachable, bad defaultFS, DNS)\n  LOG.error(\"Cannot reach metrics filesystem at {}: {}\", basePath, e.getCause(), e);\n}","preventionTips":["Sequence daemon startup after HDFS availability checks (systemd After=, k8s initContainers)","Validate the basepath URI scheme matches a configured nameservice/fs.defaultFS","Test connectivity as the daemon user with hdfs dfs -ls <basepath> during provisioning"],"tags":["metrics2","rolling-file-sink","hdfs","network","configuration"],"backgroundTag":"hdfs-connection-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}