apache/hadoop · error · IllegalArgumentException

URI resolution failed.

Error message

URI resolution failed.

What it means

BalanceJournalInfoHDFS.setConf() parses the configuration value hdfs.fedbalance.procedure.scheduler.journal.uri (FedBalanceConfigs.SCHEDULER_JOURNAL_URI) into a java.net.URI; a syntactically invalid string raises URISyntaxException, rethrown as IllegalArgumentException('URI resolution failed.') with the original exception attached. It happens when the journal store is instantiated - before any balance job runs - so fedbalance fails at startup/config time.

Source

Thrown at hadoop-tools/hadoop-federation-balance/src/main/java/org/apache/hadoop/tools/fedbalance/procedure/BalanceJournalInfoHDFS.java:163

    return jobs;
  }

  @Override
  public void clear(BalanceJob job) throws IOException {
    Path jobBase = getJobBaseDir(job);
    FileSystem fs = FileSystem.get(workUri, conf);
    if (fs.exists(jobBase)) {
      fs.delete(jobBase, true);
    }
    LOG.debug("Clear journal of job=" + job);
  }

  @Override
  public void setConf(Configuration conf) {
    try {
      this.workUri = new URI(conf.get(SCHEDULER_JOURNAL_URI));
    } catch (URISyntaxException e) {
      throw new IllegalArgumentException("URI resolution failed.", e);
    }
    this.conf = conf;
    this.generator = new IdGenerator(Time.monotonicNow());
  }

  @Override
  public Configuration getConf() {
    return conf;
  }

  private Path getJobBaseDir(BalanceJob job) {
    String jobId = job.getId();
    return new Path(workUri.getPath(), jobId);
  }

  private Path getNewStateJobPath(BalanceJob job) {
    Path basePath = getJobBaseDir(job);
    Path logPath = new Path(basePath, JOB_PREFIX + generator.nextValue());

View on GitHub (pinned to 2add963021)

Solutions

1. Set the property to a clean, fully-qualified URI, e.g. hdfs://ns1/fedbalance/journal.
2. Remove spaces and illegal characters; URL-encode anything unusual in the path.
3. Validate the value in isolation before deploying: 'jshell> new java.net.URI("hdfs://ns1/fedbalance/journal")' must not throw.

Example fix

<!-- before -->
<property>
  <name>hdfs.fedbalance.procedure.scheduler.journal.uri</name>
  <value>hdfs://ns 1/fedbalance/journal</value>
</property>

<!-- after -->
<property>
  <name>hdfs.fedbalance.procedure.scheduler.journal.uri</name>
  <value>hdfs://ns1/fedbalance/journal</value>
</property>

String v = conf.get("hdfs.fedbalance.procedure.scheduler.journal.uri");
try {
  new java.net.URI(v);   // fail fast with the real syntax error before the scheduler starts
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Bad journal URI: " + v, e);
}

try {
  info.setConf(conf);
} catch (IllegalArgumentException e) {
  if ("URI resolution failed.".equals(e.getMessage())) {
    // fix hdfs.fedbalance.procedure.scheduler.journal.uri; cause holds the URISyntaxException position
  }
}

When it happens

Trigger: Setting hdfs.fedbalance.procedure.scheduler.journal.uri to a malformed URI: embedded spaces, illegal characters, or broken scheme syntax. Note: if the key is absent entirely, new URI(null) fails with NullPointerException instead, so this exact message implies a present-but-unparseable value.

Common situations: Hand-edited site XML with an unencoded space or Windows-style backslash path; a value copied from documentation with placeholder text left in; missing scheme such as '//ns1/journal'.

Related errors

• {src} should be a directory.
• {dst} already exists.
• {src} shouldn't enable snapshot.
• DistCp failed. jobId={jobId} failure={failureInfo}
• Final DistCp failed. Failure: {failureInfo}

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