apache/hadoop · error · RuntimeException

Socket Factory class not found: ${cnfe}

Error message

Socket Factory class not found: ${cnfe}

What it means

RuntimeException('Socket Factory class not found: <cnfe>') from NetUtils.getSocketFactoryFromProperty when conf.getClassByName(propValue) raises ClassNotFoundException — the socket-factory class named by a configuration property is not loadable. It wraps the original ClassNotFoundException (whose message is embedded), so the details of the missing class survive. This runs on the RPC/client path, so a bad value typically fails at first connection setup.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetUtils.java:149

  /**
   * Get the socket factory corresponding to the given proxy URI. If the
   * given proxy URI corresponds to an absence of configuration parameter,
   * returns null. If the URI is malformed raises an exception.
   *
   * @param conf configuration.
   * @param propValue the property which is the class name of the
   *        SocketFactory to instantiate; assumed non null and non empty.
   * @return a socket factory as defined in the property value.
   */
  public static SocketFactory getSocketFactoryFromProperty(
      Configuration conf, String propValue) {

    try {
      Class<?> theClass = conf.getClassByName(propValue);
      return (SocketFactory) ReflectionUtils.newInstance(theClass, conf);

    } catch (ClassNotFoundException cnfe) {
      throw new RuntimeException("Socket Factory class not found: " + cnfe);
    }
  }

  /**
   * Util method to build socket addr from either.
   *   {@literal <host>:<port>}
   *   {@literal <fs>://<host>:<port>/<path>}
   *
   * @param target target.
   * @return socket addr.
   */
  public static InetSocketAddress createSocketAddr(String target) {
    return createSocketAddr(target, -1);
  }

  public static InetSocketAddress createSocketAddrUnresolved(String target) {
    return createSocketAddr(target, -1, null, false, false);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Check the exact class name in the property for typos (fully qualified name required)
2. Verify the class is on the classpath of every node/client: 'hadoop classpath' plus 'java -cp ... <FQCN>' probe or Class.forName check
3. Ship the jar containing the factory (e.g., add to HADOOP_CLASSPATH or lib/ directory of the service)
4. If the custom factory is no longer needed, remove the property so the default StandardSocketFactory is used

Example fix

<!-- before -->
<property><name>hadoop.rpc.socket.factory.class.default</name>
  <value>com.myco.HdfsSocketFactory</value></property> <!-- jar missing -> RuntimeException at first connect -->

<!-- after -->
<property><name>hadoop.rpc.socket.factory.class.default</name>
  <value>org.apache.hadoop.net.StandardSocketFactory</value></property>
<!-- or ship com.myco.HdfsSocketFactory's jar to all nodes -->

String factoryClass = conf.get("hadoop.rpc.socket.factory.class.default");
if (factoryClass != null) {
  Class.forName(factoryClass); // throws ClassNotFoundException early with a clear context
}

catch (RuntimeException e) { /* 'Socket Factory class not found: ...' */ report the missing FQCN and the property name; ship the jar or revert the property to StandardSocketFactory; }

When it happens

Trigger: Setting 'hadoop.rpc.socket.factory.class.default' (or a per-protocol override like 'hadoop.rpc.socket.factory.class.ClientProtocol', or fs-level 'fs.<scheme>.socket.factory') to a class name that is misspelled, not on the classpath, or whose jar is missing on the client node.

Common situations: Custom SocketFactory implementations referenced in core-site.xml but not bundled into the client/fat jar; version upgrades that moved or renamed the factory class; leftover experimental config pointing at a class removed from the build.

Related errors

• readObject can't find class {className}
• No KeyProviderFactory for ${uri} in ${KEY_PROVIDER_PATH}
• Errors on getting mount table loader class. The fs.viewfs.mo
• %s=null: %s: %s
• Could not find configured fencing method {}

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