apache/hadoop · error · MetricsException

Error connecting to file system: ${basePath} [${ex}]

Error message

Error connecting to file system: ${basePath} [${ex}]

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/metrics2/sink/RollingFileSystemSink.java:470

   * Return the supplied file system for testing or otherwise get a new file
   * system.
   *
   * @return the file system to use
   * @throws MetricsException thrown if the file system could not be retrieved
   */
  private FileSystem getFileSystem() throws MetricsException {
    FileSystem fs = null;

    if (suppliedFilesystem != null) {
      fs = suppliedFilesystem;
    } else {
      try {
        fs = FileSystem.get(new URI(basePath.toString()), conf);
      } catch (URISyntaxException ex) {
        throw new MetricsException("The supplied filesystem base path URI"
            + " is not a valid URI: " + basePath.toString(), ex);
      } catch (IOException ex) {
        throw new MetricsException("Error connecting to file system: "
            + basePath + " [" + ex.toString() + "]", ex);
      }
    }

    return fs;
  }

  /**
   * Test whether the file system supports append and return the answer.
   *
   * @param fs the target file system
   */
  private boolean checkAppend(FileSystem fs) {
    boolean canAppend = true;

    try {
      fs.append(basePath);
    } catch (UnsupportedOperationException ex) {

View on GitHub (pinned to 2add963021)

Solutions

1. Verify the filesystem is reachable as the daemon user: hdfs dfs -ls <basepath>
2. Fix fs.defaultFS / dfs.nameservices / HA RPC address configuration for the scheme used in basepath
3. Restart the daemon after HDFS recovers — this connection is attempted only at initialization
4. Check the bracketed cause in the message; it distinguishes DNS, timeout and refusal

FileSystem fs = FileSystem.get(new URI(basePath.toString()), conf);
fs.exists(basePath); // forces connection now, surfacing IOException before the daemon relies on the sink

try {
  sink.init(subsetConf);
} catch (MetricsException e) {
  // message embeds basePath and the original IOException (NN unreachable, bad defaultFS, DNS)
  LOG.error("Cannot reach metrics filesystem at {}: {}", basePath, e.getCause(), e);
}

When it happens

Trigger: 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.

Common situations: Daemons starting before HDFS is fully up; fs.defaultFS or nameservice RPC addresses misconfigured; DNS outages in containers.

Related errors

• Failed to create ${basePath}[source=${source}, allow-append=
• Error creating connection, {}:{}
• Unrecognized flush interval: ${rollInterval}. Must be a numb
• Unrecognized unit for flush interval: ${flushUnit}. Must be
• The flush interval property must be at least 1 minute. Value

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/6e74ac6297896583. Report an issue: GitHub.