apache/hadoop · error · HadoopIllegalArgumentException

{feature} is enabled but dfs.domain.socket.path is not set.

Error message

{feature} is enabled but dfs.domain.socket.path is not set.

What it means

DomainSocketFactory's constructor requires a UNIX domain socket path whenever short-circuit local reads (dfs.client.read.shortcircuit=true) or domain-socket data traffic (dfs.client.domain.socket.data.traffic=true) is enabled. If dfs.domain.socket.path is unset/empty it throws HadoopIllegalArgumentException immediately when the DFSClient is constructed.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/shortcircuit/DomainSocketFactory.java:113

  private final long pathExpireSeconds;
  private final Cache<String, PathState> pathMap;

  public DomainSocketFactory(ShortCircuitConf conf) {
    final String feature;
    if (conf.isShortCircuitLocalReads() && (!conf.isUseLegacyBlockReaderLocal())) {
      feature = "The short-circuit local reads feature";
    } else if (conf.isDomainSocketDataTraffic()) {
      feature = "UNIX domain socket data traffic";
    } else {
      feature = null;
    }

    if (feature == null) {
      PerformanceAdvisory.LOG.debug(
          "Both short-circuit local reads and UNIX domain socket are disabled.");
    } else {
      if (conf.getDomainSocketPath().isEmpty()) {
        throw new HadoopIllegalArgumentException(feature + " is enabled but "
            + HdfsClientConfigKeys.DFS_DOMAIN_SOCKET_PATH_KEY + " is not set.");
      } else if (DomainSocket.getLoadingFailureReason() != null) {
        LOG.warn(feature + " cannot be used because "
            + DomainSocket.getLoadingFailureReason());
      } else {
        LOG.debug(feature + " is enabled.");
      }
    }

    pathExpireSeconds = conf.getDomainSocketDisableIntervalSeconds();
    pathMap = CacheBuilder.newBuilder()
        .expireAfterWrite(pathExpireSeconds, TimeUnit.SECONDS).build();
  }

  /**
   * Get information about a domain socket path.
   *
   * @param addr         The inet address to use.

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.domain.socket.path to the same path the DataNode uses (e.g. /var/lib/hadoop-hdfs/dn_socket)
2. Confirm the DataNode actually created the socket and the parent directory permissions allow the client
3. If short-circuit is not needed, leave dfs.client.read.shortcircuit=false and dfs.client.domain.socket.data.traffic=false

Example fix

<!-- before -->
<property>
  <name>dfs.client.read.shortcircuit</name>
  <value>true</value>
</property>

<!-- after -->
<property>
  <name>dfs.client.read.shortcircuit</name>
  <value>true</value>
</property>
<property>
  <name>dfs.domain.socket.path</name>
  <value>/var/lib/hadoop-hdfs/dn_socket</value>
</property>

boolean needsSocket = conf.getBoolean("dfs.client.read.shortcircuit", false)
    || conf.getBoolean("dfs.client.domain.socket.data.traffic", false);
if (needsSocket && conf.getTrimmed("dfs.domain.socket.path", "").isEmpty()) {
  throw new IllegalArgumentException(
      "dfs.domain.socket.path must be set when short-circuit reads "
      + "or domain socket data traffic are enabled");
}

catch (HadoopIllegalArgumentException e) at FileSystem construction mentioning dfs.domain.socket.path: fail fast with a config checklist.

When it happens

Trigger: Enabling either feature in the client Configuration used to create the FileSystem/DFSClient without setting dfs.domain.socket.path.

Common situations: Performance-tuning guides enabling short-circuit reads while skipping the socket path; client config diverging from the DataNode's dfs.domain.socket.path value.

Related errors

• no SharedFileDescriptorFactory paths were configured.
• You cannot pass file descriptors over anything but a UNIX do
• got EOF while trying to transfer the file descriptor for the
• Can not create a Path from a null string
• Can not create a Path from an empty string

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