{"record":{"id":"8140828b044645b7","repo":"apache/hadoop","slug":"unable-to-instantiate-copylistingclassname","errorCode":null,"errorMessage":"Unable to instantiate \" + copyListingClassName","messagePattern":"Unable to instantiate \" \\+ copyListingClassName","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/CopyListing.java","lineNumber":304,"sourceCode":"    Class<? extends CopyListing> copyListingClass;\n    try {\n      if (! copyListingClassName.isEmpty()) {\n        copyListingClass = configuration.getClass(DistCpConstants.\n            CONF_LABEL_COPY_LISTING_CLASS, GlobbedCopyListing.class,\n            CopyListing.class);\n      } else {\n        if (context.getSourceFileListing() == null) {\n            copyListingClass = GlobbedCopyListing.class;\n        } else {\n            copyListingClass = FileBasedCopyListing.class;\n        }\n      }\n      copyListingClassName = copyListingClass.getName();\n      Constructor<? extends CopyListing> constructor = copyListingClass.\n          getDeclaredConstructor(Configuration.class, Credentials.class);\n      return constructor.newInstance(configuration, credentials);\n    } catch (Exception e) {\n      throw new IOException(\"Unable to instantiate \" + copyListingClassName, e);\n    }\n  }\n\n  static class DuplicateFileException extends RuntimeException {\n    public DuplicateFileException(String message) {\n      super(message);\n    }\n  }\n\n  static class InvalidInputException extends RuntimeException {\n    public InvalidInputException(String message) {\n      super(message);\n    }\n\n    public InvalidInputException(String message, Throwable cause) {\n      super(message, cause);\n    }\n  }","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/CopyListing.java#L286-L322","documentation":"CopyListing.getCopyListing picks the listing implementation — from distcp.copy.listing.class when set, otherwise GlobbedCopyListing or FileBasedCopyListing depending on whether a source file listing was supplied — and reflectively constructs it via its (Configuration, Credentials) constructor. Any reflective failure is rethrown as IOException('Unable to instantiate <class name>') with the cause attached.","triggerScenarios":"Configuring distcp.copy.listing.class to a custom class whose constructor is not exactly (Configuration, Credentials) or is non-public; the class missing from the client/task classpath; or the constructor throwing during instantiation.","commonSituations":"Custom CopyListing implementations drifting from the required constructor signature across versions; jar packaging differences between client and MR tasks; class-name typos in the configuration.","solutions":["Ensure the class extends CopyListing with a public constructor taking exactly (Configuration, Credentials)","Ship it on the distcp classpath for both client and tasks (e.g. -libjars)","Read the cause: ClassNotFoundException -> classpath, NoSuchMethodException -> signature, InvocationTargetException -> constructor threw","Unset distcp.copy.listing.class to fall back to the default listing and isolate the issue"],"exampleFix":"// before: wrong constructor signature\npublic class MyListing extends CopyListing {\n  public MyListing(Configuration conf) { super(conf); }\n}\n// -> IOException: Unable to instantiate com.example.MyListing\n\n// after\npublic class MyListing extends CopyListing {\n  public MyListing(Configuration conf, Credentials credentials) {\n    super(conf, credentials);\n  }\n}","handlingStrategy":"try-catch","validationCode":"String cls = conf.get(DistCpConstants.CONF_LABEL_COPY_LISTING_CLASS, \"\");\nif (!cls.isEmpty()) {\n  Class<?> c = Class.forName(cls);\n  if (!CopyListing.class.isAssignableFrom(c)) {\n    throw new IllegalArgumentException(cls + \" must extend CopyListing\");\n  }\n  c.getConstructor(Configuration.class, Credentials.class); // fail fast\n}","typeGuard":null,"tryCatchPattern":"Catch IOException around DistCp.execute(); when the message starts with 'Unable to instantiate' plus the listing class name, inspect the cause to distinguish classpath (ClassNotFoundException), constructor signature (NoSuchMethodException), or constructor failure (InvocationTargetException), then fix and rerun.","preventionTips":["Custom CopyListing implementations must expose a public (Configuration, Credentials) constructor","Add a reflective instantiation unit test mirroring CopyListing.getCopyListing","Ship custom classes via -libjars so client and tasks agree on the implementation"],"tags":["distcp","reflection","copy-listing","classloading","configuration"],"backgroundTag":"class-instantiation-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}