apache/hadoop · error · IllegalArgumentException

Journal dir '{}' should be an absolute path

Error message

Journal dir '{}' should be an absolute path

What it means

JournalNode.validateAndCreateJournalDir throws IllegalArgumentException at startup when any directory in dfs.journalnode.edits.dir is not absolute (File.isAbsolute() is false). Edit directories are used to build storage layout paths and are persisted in VERSION files, so relative paths that depend on the process CWD are rejected outright. This is a configuration sanity check that fails fast during JournalNode (or a tool using it) initialization.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/qjournal/server/JournalNode.java:203

      if (journalNodeDir == null) {
        journalNodeDir = conf.get(DFSConfigKeys.DFS_JOURNALNODE_EDITS_DIR_KEY,
            DFSConfigKeys.DFS_JOURNALNODE_EDITS_DIR_DEFAULT);
      }
      localDir.add(new File(journalNodeDir.trim()));
    }

    if (this.tracer == null) {
      this.tracer = new Tracer.Builder("JournalNode").
          conf(TraceUtils.wrapHadoopConf("journalnode.htrace", conf)).
          build();
    }
  }

  private static void validateAndCreateJournalDir(File dir)
      throws IOException {

    if (!dir.isAbsolute()) {
      throw new IllegalArgumentException(
          "Journal dir '" + dir + "' should be an absolute path");
    }
    DiskChecker.checkDir(dir);
  }

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

  @Override
  public int run(String[] args) throws Exception {
    start();
    return join();
  }

  /**
   * Start listening for edits via RPC.

View on GitHub (pinned to 2add963021)

Solutions

1. Edit hdfs-site.xml and give every dfs.journalnode.edits.dir entry a fully qualified absolute path (e.g., file:///data/journaldata or /data/journaldata).
2. Replace '~' with the literal home directory or an env-var-expanded absolute path in your config management (Ansible/Chef templates are the usual culprit).
3. Re-run the JournalNode and confirm it passes storage dir validation and starts the RPC server.
4. If multiple dirs are configured, fix all of them — validation iterates each and fails on the first relative one.

Example fix

<!-- before -->
<property>
  <name>dfs.journalnode.edits.dir</name>
  <value>journaldata</value>
</property>
<!-- IllegalArgumentException: Journal dir 'journaldata' should be an absolute path -->

<!-- after -->
<property>
  <name>dfs.journalnode.edits.dir</name>
  <value>/data/journaldata</value>
</property>

for (URI u : JournalNode.getJournalDirList(conf)) {
  File dir = new File(u.getPath());
  if (!dir.isAbsolute()) {
    throw new IllegalArgumentException("Fix config: " + u + " must be absolute");
  }
}

When it happens

Trigger: JournalNode starts with dfs.journalnode.edits.dir containing an entry like 'journaldata' or '~/journal' (the '~' is not expanded by Java), so dir.isAbsolute() is false. Each configured dir passes through validateAndCreateJournalDir before use.

Common situations: Using '~' or a relative directory in hdfs-site.xml (Java does not expand shell syntax); config generated from templates with an empty $VAR base path producing ' /jndir' or a bare suffix; running the JournalNode from a different working directory than in dev and only then noticing the relative path; systemd unit with non-obvious CWD.

Related errors

• Can not create a Path from a null string
• Can not create a Path from an empty string
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with

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