apache/hadoop · error · MetricsException

The supplied filesystem base path URI is not a valid URI: ${

Error message

The supplied filesystem base path URI is not a valid URI: ${basePath}

What it means

getFileSystem() builds new URI(basePath.toString()) to obtain the FileSystem for the sink's basepath. basePath is itself constructed via new Path(<basepath property>), which accepts characters that are illegal in a URI — spaces, percent signs, some non-ASCII — so the URI constructor can throw URISyntaxException, wrapped here with the offending path in the message.

Source

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

  }

  /**
   * 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;

View on GitHub (pinned to 2add963021)

Solutions

1. Remove or encode the offending characters (replace spaces or percent-encode them)
2. Prefer a clean scheme-qualified path: basepath=hdfs://nameservice/metrics
3. Test the value: new URI(new Path(value).toString()) in a scratch program or jshell before deploying

Example fix

# before
*.sink.rolling.basepath=/tmp/hadoop metrics/  # space makes basePath an invalid URI

# after
*.sink.rolling.basepath=/tmp/hadoop-metrics/

try {
  new URI(new Path(basepathValue).toString());
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("basepath '" + basepathValue
      + "' is not URI-safe (spaces/special chars?): " + e.getReason(), e);
}

try {
  sink.init(subsetConf);
} catch (MetricsException e) {
  // 'The supplied filesystem base path URI is not a valid URI' — sanitize the basepath value
  LOG.error("basepath '{}' contains URI-illegal characters", basepath, e);
}

When it happens

Trigger: basepath containing URI-hostile characters, e.g. basepath=/metrics my logs or hdfs://nn/user/hdfs/metrics (old) where the directory name has a space or stray % character.

Common situations: Paths copied from shell commands or documentation containing spaces; directory names with special characters; Windows-style paths with drive letters in exotic setups.

Related errors

• Failed to create ${basePath}[source=${source}, allow-append=
• 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
• The ${key} property must be non-negative. Value was ${value}

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