{"record":{"id":"ac01b6fa9a9ee12b","repo":"apache/hadoop","slug":"although-a-unix-domain-socket-path-is-configured-a","errorCode":null,"errorMessage":"Although a UNIX domain socket path is configured as {domainSocketPath}, we cannot start a localDataXceiverServer because {loadingFailureReason}","messagePattern":"Although a UNIX domain socket path is configured as (.+?), we cannot start a localDataXceiverServer because (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataNode.java","lineNumber":1723,"sourceCode":"\n  private static DomainPeerServer getDomainPeerServer(Configuration conf,\n      int port) throws IOException {\n    String domainSocketPath =\n        conf.getTrimmed(DFSConfigKeys.DFS_DOMAIN_SOCKET_PATH_KEY,\n            DFSConfigKeys.DFS_DOMAIN_SOCKET_PATH_DEFAULT);\n    if (domainSocketPath.isEmpty()) {\n      if (conf.getBoolean(HdfsClientConfigKeys.Read.ShortCircuit.KEY,\n            HdfsClientConfigKeys.Read.ShortCircuit.DEFAULT) &&\n         (!conf.getBoolean(HdfsClientConfigKeys.DFS_CLIENT_USE_LEGACY_BLOCKREADERLOCAL,\n          HdfsClientConfigKeys.DFS_CLIENT_USE_LEGACY_BLOCKREADERLOCAL_DEFAULT))) {\n        LOG.warn(\"Although short-circuit local reads are configured, \" +\n            \"they are disabled because you didn't configure {}\",\n            DFSConfigKeys.DFS_DOMAIN_SOCKET_PATH_KEY);\n      }\n      return null;\n    }\n    if (DomainSocket.getLoadingFailureReason() != null) {\n      throw new RuntimeException(\"Although a UNIX domain socket \" +\n          \"path is configured as \" + domainSocketPath + \", we cannot \" +\n          \"start a localDataXceiverServer because \" +\n          DomainSocket.getLoadingFailureReason());\n    }\n    DomainPeerServer domainPeerServer =\n      new DomainPeerServer(domainSocketPath, port);\n    int recvBufferSize = conf.getInt(\n        DFSConfigKeys.DFS_DATANODE_TRANSFER_SOCKET_RECV_BUFFER_SIZE_KEY,\n        DFSConfigKeys.DFS_DATANODE_TRANSFER_SOCKET_RECV_BUFFER_SIZE_DEFAULT);\n    if (recvBufferSize > 0) {\n      domainPeerServer.setReceiveBufferSize(recvBufferSize);\n    }\n    return domainPeerServer;\n  }\n  \n  // calls specific to BP\n  public void notifyNamenodeReceivedBlock(ExtendedBlock block, String delHint,\n      String storageUuid, boolean isOnTransientStorage) {","sourceCodeStart":1705,"sourceCodeEnd":1741,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataNode.java#L1705-L1741","documentation":"When dfs.domain.socket.path is configured, initDomainSocketPeerServer needs the native DomainSocket binding; DomainSocket.getLoadingFailureReason() is non-null exactly when the native Hadoop library (libhadoop.so) failed to load, and the DN then aborts startup with this RuntimeException rather than run a half-working short-circuit stack. This is about native library availability, not socket-path permissions (those fail later at bind time).","triggerScenarios":"dfs.domain.socket.path set (for short-circuit reads / DomainPeerServer traffic) on a JVM where NativeCodeLoader failed: libhadoop.so missing, wrong architecture, glibc mismatch, LD_LIBRARY_PATH/JAVA_LIBRARY_PATH unset, or a platform without UNIX domain socket support (e.g. Windows).","commonSituations":"Short-circuit read rollouts where docs set dfs.domain.socket.path but native libs were never installed; slim Docker images stripping .so files; OS/JDK upgrades leaving stale native artifacts; hardened base images.","solutions":["Fix native support on the DN host: 'hadoop checknative -a' must report native:true; deploy matching libhadoop.so under $HADOOP_HOME/lib/native and set LD_LIBRARY_PATH accordingly","If short-circuit reads are not required, remove dfs.domain.socket.path from hdfs-site.xml — the DN then only logs a warning and skips the local xceiver server","After fixing, restart the DN and confirm the socket file appears: ls -l /var/lib/hadoop-hdfs/dn_socket"],"exampleFix":"<!-- before -->\n<property><name>dfs.domain.socket.path</name><value>/var/lib/hadoop-hdfs/dn_socket</value></property>\n<!-- after: no native libs, short-circuit reads not needed -->\n<!-- property removed; set dfs.client.read.shortcircuit=false on clients -->","handlingStrategy":"validation","validationCode":"String path = conf.get(DFSConfigKeys.DFS_DOMAIN_SOCKET_PATH_KEY, \"\");\nif (!path.isEmpty() && DomainSocket.getLoadingFailureReason() != null) {\n  throw new IllegalStateException(\"dfs.domain.socket.path set but native DomainSocket unavailable: \"\n      + DomainSocket.getLoadingFailureReason());\n}","typeGuard":null,"tryCatchPattern":"catch (RuntimeException e) {\n  if (e.getMessage().contains(\"cannot start a localDataXceiverServer\")) {\n    // run hadoop checknative -a, fix libhadoop.so, or unset dfs.domain.socket.path and restart\n  }\n}","preventionTips":["Run 'hadoop checknative -a' on every DN host before enabling short-circuit reads","Bake libhadoop.so into deployment images and verify after OS/JDK upgrades","If native support is uncertain, leave dfs.domain.socket.path unset — the DN only warns"],"tags":["hadoop","hdfs","datanode","native-library","short-circuit-reads","unix-socket","startup"],"backgroundTag":"native-library-load-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}