{"record":{"id":"86a206df44b64814","repo":"apache/hadoop","slug":"cannot-find-subcluster-resolver","errorCode":null,"errorMessage":"Cannot find subcluster resolver","messagePattern":"Cannot find subcluster resolver","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/Router.java","lineNumber":187,"sourceCode":"    if (conf.getBoolean(\n        RBFConfigKeys.DFS_ROUTER_STORE_ENABLE,\n        RBFConfigKeys.DFS_ROUTER_STORE_ENABLE_DEFAULT)) {\n      // Service that maintains the State Store connection\n      this.stateStore = new StateStoreService();\n      addService(this.stateStore);\n    }\n\n    // Resolver to track active NNs\n    this.namenodeResolver = newActiveNamenodeResolver(\n        this.conf, this.stateStore);\n    if (this.namenodeResolver == null) {\n      throw new IOException(\"Cannot find namenode resolver.\");\n    }\n\n    // Lookup interface to map between the global and subcluster name spaces\n    this.subclusterResolver = newFileSubclusterResolver(this.conf, this);\n    if (this.subclusterResolver == null) {\n      throw new IOException(\"Cannot find subcluster resolver\");\n    }\n\n    if (conf.getBoolean(\n        RBFConfigKeys.DFS_ROUTER_RPC_ENABLE,\n        RBFConfigKeys.DFS_ROUTER_RPC_ENABLE_DEFAULT)) {\n      // Create RPC server\n      this.rpcServer = createRpcServer();\n      addService(this.rpcServer);\n      this.setRpcServerAddress(rpcServer.getRpcAddress());\n    }\n\n    checkRouterId();\n\n    if (conf.getBoolean(\n        RBFConfigKeys.DFS_ROUTER_ADMIN_ENABLE,\n        RBFConfigKeys.DFS_ROUTER_ADMIN_ENABLE_DEFAULT)) {\n      // Create admin server\n      this.adminServer = createAdminServer();","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/Router.java#L169-L205","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the preceding 'Could not instantiate' log entry to get the true reflective failure","Correct or remove dfs.federation.router.file.resolver.client.class (default MountTableResolver works for standard mount-table federation)","Ensure the custom class implements FileSubclusterResolver with a (Configuration, Router) constructor and its jar is on every Router's classpath"],"exampleFix":"# before: custom class missing from classpath\ndfs.federation.router.file.resolver.client.class = com.myco.MyFileResolver\n\n# after: revert to default\n# (delete the key) -> MountTableResolver","handlingStrategy":"validation","validationCode":"String cls = conf.get(\"dfs.federation.router.file.resolver.client.class\",\n    \"org.apache.hadoop.hdfs.server.federation.resolver.MountTableResolver\");\nClass<?> c = Class.forName(cls);\nif (!org.apache.hadoop.hdfs.server.federation.resolver.FileSubclusterResolver.class.isAssignableFrom(c)) {\n  throw new IllegalArgumentException(cls + \" does not implement FileSubclusterResolver\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  router.init(conf);\n} catch (IOException e) {\n  if (\"Cannot find subcluster resolver\".equals(e.getMessage())) {\n    // check preceding 'Could not instantiate' log; fix or unset\n    // dfs.federation.router.file.resolver.client.class and redeploy\n  } else { throw e; }\n}","preventionTips":["Default to MountTableResolver unless a custom resolver is fully tested","Ensure custom resolver classes ship in the Router's classpath on every node","Validate plugin classes with Class.forName in deployment checks"],"tags":["hdfs","router-based-federation","startup","configuration","resolver","reflection"],"backgroundTag":"class-instantiation-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}