{"record":{"id":"27326f2840c5e8f5","repo":"apache/hadoop","slug":"unable-to-instantiate-filtersclassname","errorCode":null,"errorMessage":"Unable to instantiate \" + filtersClassName","messagePattern":"Unable to instantiate \" \\+ filtersClassName","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/CopyFilter.java","lineNumber":71,"sourceCode":"   * @param conf DistCp configuration\n   * @return An instance of the appropriate CopyFilter\n   */\n  public static CopyFilter getCopyFilter(Configuration conf) {\n    String filtersClassName = conf\n            .get(DistCpConstants.CONF_LABEL_FILTERS_CLASS);\n    if (filtersClassName != null) {\n      try {\n        Class<? extends CopyFilter> filtersClass = conf\n                .getClassByName(filtersClassName)\n                .asSubclass(CopyFilter.class);\n        filtersClassName = filtersClass.getName();\n        Constructor<? extends CopyFilter> constructor = filtersClass\n                .getDeclaredConstructor(Configuration.class);\n        return constructor.newInstance(conf);\n      } catch (Exception e) {\n        LOG.error(DistCpConstants.CLASS_INSTANTIATION_ERROR_MSG +\n                filtersClassName, e);\n        throw new RuntimeException(\n                DistCpConstants.CLASS_INSTANTIATION_ERROR_MSG +\n                        filtersClassName, e);\n      }\n    } else {\n      return getDefaultCopyFilter(conf);\n    }\n  }\n\n  private static CopyFilter getDefaultCopyFilter(Configuration conf) {\n    String filtersFilename = conf.get(DistCpConstants.CONF_LABEL_FILTERS_FILE);\n\n    if (filtersFilename == null) {\n      return new TrueCopyFilter();\n    } else {\n      String filterFilename = conf.get(\n          DistCpConstants.CONF_LABEL_FILTERS_FILE);\n      return new RegexCopyFilter(filterFilename);\n    }","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/CopyFilter.java#L53-L89","documentation":"DistCp's CopyFilter.getCopyFilter reflectively loads the class named by distcp.filters.class, requires it to subclass CopyFilter with a constructor taking exactly Configuration, and instantiates it. Any failure — class not on the classpath, not a CopyFilter subclass, missing/non-public constructor, or the constructor itself throwing — is wrapped in a RuntimeException prefixed with 'Unable to instantiate <classname>' (DistCpConstants.CLASS_INSTANTIATION_ERROR_MSG), and the cause is both logged via LOG.error and attached.","triggerScenarios":"Setting distcp.filters.class to a custom filter class that (a) is not on the client and MR-task classpath, (b) does not extend CopyFilter, (c) lacks a public constructor with the exact signature CopyFilter(Configuration), or (d) whose constructor throws (e.g. it reads a config key that is absent).","commonSituations":"Custom filter jar not shipped to cluster nodes (works locally, fails in the MR job); refactoring changed the constructor signature; typo in the class name; filter logic requiring a filters file that was not provided.","solutions":["Make the class public, extend org.apache.hadoop.tools.CopyFilter, and expose a public constructor taking exactly Configuration","Ship the filter jar where both the client and the MR tasks load it (distcp -libjars or the cluster share dir)","Read the LOG.error line and the attached cause: ClassNotFoundException means classpath, NoSuchMethodException means signature, InvocationTargetException means the constructor threw","Temporarily unset distcp.filters.class to confirm the default (regex) filter path works, isolating the problem"],"exampleFix":"// before: only a no-arg constructor\npublic class MyFilter extends CopyFilter {\n  public MyFilter() { }\n}\n// -> RuntimeException: Unable to instantiate com.example.MyFilter\n\n// after\npublic class MyFilter extends CopyFilter {\n  public MyFilter(Configuration conf) { super(conf); }\n}","handlingStrategy":"try-catch","validationCode":"String cls = conf.get(DistCpConstants.CONF_LABEL_FILTERS_CLASS);\nif (cls != null) {\n  Class<?> c = Class.forName(cls);\n  if (!CopyFilter.class.isAssignableFrom(c)\n      || !Modifier.isPublic(c.getModifiers())) {\n    throw new IllegalArgumentException(\n        cls + \" must be a public CopyFilter subclass\");\n  }\n  c.getConstructor(Configuration.class); // NoSuchMethodException -> fail fast\n}","typeGuard":null,"tryCatchPattern":"Catch RuntimeException around DistCp execution; when the message starts with 'Unable to instantiate' plus your filter class name, inspect the cause — ClassNotFoundException means classpath, NoSuchMethodException means the (Configuration) constructor is missing, InvocationTargetException means the constructor threw — fix accordingly and rerun.","preventionTips":["Give every custom filter a public constructor taking exactly Configuration","Unit-test filters by instantiating them reflectively the way CopyFilter.getCopyFilter does","Use -libjars so client and MR tasks load the identical filter class"],"tags":["distcp","reflection","filters","classloading","configuration"],"backgroundTag":"class-instantiation-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}