{"record":{"id":"dbf6c9a1dbe17fd6","repo":"apache/hadoop","slug":"feature-is-enabled-but-dfs-domain-socket-path-is","errorCode":null,"errorMessage":"{feature} is enabled but dfs.domain.socket.path is not set.","messagePattern":"(.+?) is enabled but dfs\\.domain\\.socket\\.path is not set\\.","errorType":"validation","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/shortcircuit/DomainSocketFactory.java","lineNumber":113,"sourceCode":"  private final long pathExpireSeconds;\n  private final Cache<String, PathState> pathMap;\n\n  public DomainSocketFactory(ShortCircuitConf conf) {\n    final String feature;\n    if (conf.isShortCircuitLocalReads() && (!conf.isUseLegacyBlockReaderLocal())) {\n      feature = \"The short-circuit local reads feature\";\n    } else if (conf.isDomainSocketDataTraffic()) {\n      feature = \"UNIX domain socket data traffic\";\n    } else {\n      feature = null;\n    }\n\n    if (feature == null) {\n      PerformanceAdvisory.LOG.debug(\n          \"Both short-circuit local reads and UNIX domain socket are disabled.\");\n    } else {\n      if (conf.getDomainSocketPath().isEmpty()) {\n        throw new HadoopIllegalArgumentException(feature + \" is enabled but \"\n            + HdfsClientConfigKeys.DFS_DOMAIN_SOCKET_PATH_KEY + \" is not set.\");\n      } else if (DomainSocket.getLoadingFailureReason() != null) {\n        LOG.warn(feature + \" cannot be used because \"\n            + DomainSocket.getLoadingFailureReason());\n      } else {\n        LOG.debug(feature + \" is enabled.\");\n      }\n    }\n\n    pathExpireSeconds = conf.getDomainSocketDisableIntervalSeconds();\n    pathMap = CacheBuilder.newBuilder()\n        .expireAfterWrite(pathExpireSeconds, TimeUnit.SECONDS).build();\n  }\n\n  /**\n   * Get information about a domain socket path.\n   *\n   * @param addr         The inet address to use.","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/shortcircuit/DomainSocketFactory.java#L95-L131","documentation":"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.","triggerScenarios":"Enabling either feature in the client Configuration used to create the FileSystem/DFSClient without setting dfs.domain.socket.path.","commonSituations":"Performance-tuning guides enabling short-circuit reads while skipping the socket path; client config diverging from the DataNode's dfs.domain.socket.path value.","solutions":["Set dfs.domain.socket.path to the same path the DataNode uses (e.g. /var/lib/hadoop-hdfs/dn_socket)","Confirm the DataNode actually created the socket and the parent directory permissions allow the client","If short-circuit is not needed, leave dfs.client.read.shortcircuit=false and dfs.client.domain.socket.data.traffic=false"],"exampleFix":"<!-- before -->\n<property>\n  <name>dfs.client.read.shortcircuit</name>\n  <value>true</value>\n</property>\n\n<!-- after -->\n<property>\n  <name>dfs.client.read.shortcircuit</name>\n  <value>true</value>\n</property>\n<property>\n  <name>dfs.domain.socket.path</name>\n  <value>/var/lib/hadoop-hdfs/dn_socket</value>\n</property>","handlingStrategy":"validation","validationCode":"boolean needsSocket = conf.getBoolean(\"dfs.client.read.shortcircuit\", false)\n    || conf.getBoolean(\"dfs.client.domain.socket.data.traffic\", false);\nif (needsSocket && conf.getTrimmed(\"dfs.domain.socket.path\", \"\").isEmpty()) {\n  throw new IllegalArgumentException(\n      \"dfs.domain.socket.path must be set when short-circuit reads \"\n      + \"or domain socket data traffic are enabled\");\n}","typeGuard":null,"tryCatchPattern":"catch (HadoopIllegalArgumentException e) at FileSystem construction mentioning dfs.domain.socket.path: fail fast with a config checklist.","preventionTips":["Set dfs.domain.socket.path at the same time you enable short-circuit reads","Mirror the DataNode's socket path value in client configs via templating","Verify the DN created the socket file before enabling the feature cluster-wide"],"tags":["hdfs","short-circuit-reads","configuration","unix-domain-socket"],"backgroundTag":"missing-required-config","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}