apache/hadoop · critical · IOException

Cannot find subcluster resolver

Error message

Cannot find subcluster resolver

What it means

Router.init() builds the file-to-subcluster resolver from dfs.federation.router.file.resolver.client.class (default MountTableResolver) via reflection. If the class cannot be instantiated (missing class, wrong constructor, constructor exception), newFileSubclusterResolver returns null and Router startup aborts with IOException('Cannot find subcluster resolver'). The instantiation failure is logged as 'Could not instantiate: <class>' immediately before.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/Router.java:187

    if (conf.getBoolean(
        RBFConfigKeys.DFS_ROUTER_STORE_ENABLE,
        RBFConfigKeys.DFS_ROUTER_STORE_ENABLE_DEFAULT)) {
      // Service that maintains the State Store connection
      this.stateStore = new StateStoreService();
      addService(this.stateStore);
    }

    // Resolver to track active NNs
    this.namenodeResolver = newActiveNamenodeResolver(
        this.conf, this.stateStore);
    if (this.namenodeResolver == null) {
      throw new IOException("Cannot find namenode resolver.");
    }

    // Lookup interface to map between the global and subcluster name spaces
    this.subclusterResolver = newFileSubclusterResolver(this.conf, this);
    if (this.subclusterResolver == null) {
      throw new IOException("Cannot find subcluster resolver");
    }

    if (conf.getBoolean(
        RBFConfigKeys.DFS_ROUTER_RPC_ENABLE,
        RBFConfigKeys.DFS_ROUTER_RPC_ENABLE_DEFAULT)) {
      // Create RPC server
      this.rpcServer = createRpcServer();
      addService(this.rpcServer);
      this.setRpcServerAddress(rpcServer.getRpcAddress());
    }

    checkRouterId();

    if (conf.getBoolean(
        RBFConfigKeys.DFS_ROUTER_ADMIN_ENABLE,
        RBFConfigKeys.DFS_ROUTER_ADMIN_ENABLE_DEFAULT)) {
      // Create admin server
      this.adminServer = createAdminServer();

View on GitHub (pinned to 2add963021)

Solutions

1. Read the preceding 'Could not instantiate' log entry to get the true reflective failure
2. Correct or remove dfs.federation.router.file.resolver.client.class (default MountTableResolver works for standard mount-table federation)
3. Ensure the custom class implements FileSubclusterResolver with a (Configuration, Router) constructor and its jar is on every Router's classpath

Example fix

# before: custom class missing from classpath
dfs.federation.router.file.resolver.client.class = com.myco.MyFileResolver

# after: revert to default
# (delete the key) -> MountTableResolver

String cls = conf.get("dfs.federation.router.file.resolver.client.class",
    "org.apache.hadoop.hdfs.server.federation.resolver.MountTableResolver");
Class<?> c = Class.forName(cls);
if (!org.apache.hadoop.hdfs.server.federation.resolver.FileSubclusterResolver.class.isAssignableFrom(c)) {
  throw new IllegalArgumentException(cls + " does not implement FileSubclusterResolver");
}

try {
  router.init(conf);
} catch (IOException e) {
  if ("Cannot find subcluster resolver".equals(e.getMessage())) {
    // check preceding 'Could not instantiate' log; fix or unset
    // dfs.federation.router.file.resolver.client.class and redeploy
  } else { throw e; }
}

When it happens

Trigger: Configuring dfs.federation.router.file.resolver.client.class with a class that is not on the classpath or lacks a (Configuration, Router) constructor; a custom FileSubclusterResolver whose constructor throws (e.g. it fails to read its own config); jar packaging errors after an upgrade.

Common situations: Custom resolver plugin only deployed to part of the Router fleet; typo in the config value; class renamed between Hadoop versions; shade plugin stripping plugin classes.

Related errors

• Cannot find namenode resolver.
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with
• Journal dir '{}' should be an absolute path

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