{"record":{"id":"8854cf8897bc6384","repo":"apache/hadoop","slug":"the-datanode-failed-to-pass-a-file-descriptor-f","errorCode":null,"errorMessage":"the datanode {} failed to pass a file descriptor for the shared memory segment.","messagePattern":"the datanode (.+?) failed to pass a file descriptor for the shared memory segment\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"warning","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/shortcircuit/DfsClientShmManager.java","lineNumber":176,"sourceCode":"      final DataOutputStream out =\n          new DataOutputStream(\n              new BufferedOutputStream(peer.getOutputStream()));\n      new Sender(out).requestShortCircuitShm(clientName);\n      ShortCircuitShmResponseProto resp =\n          ShortCircuitShmResponseProto.parseFrom(\n            PBHelperClient.vintPrefixed(peer.getInputStream()));\n      String error = resp.hasError() ? resp.getError() : \"(unknown)\";\n      switch (resp.getStatus()) {\n      case SUCCESS:\n        DomainSocket sock = peer.getDomainSocket();\n        byte buf[] = new byte[1];\n        FileInputStream[] fis = new FileInputStream[1];\n        if (sock.recvFileInputStreams(fis, buf, 0, buf.length) < 0) {\n          throw new EOFException(\"got EOF while trying to transfer the \" +\n              \"file descriptor for the shared memory segment.\");\n        }\n        if (fis[0] == null) {\n          throw new IOException(\"the datanode \" + datanode + \" failed to \" +\n              \"pass a file descriptor for the shared memory segment.\");\n        }\n        try {\n          DfsClientShm shm =\n              new DfsClientShm(PBHelperClient.convert(resp.getId()),\n                  fis[0], this, peer);\n          LOG.trace(\"{}: createNewShm: created {}\", this, shm);\n          return shm;\n        } finally {\n          try {\n            fis[0].close();\n          } catch (Throwable e) {\n            LOG.debug(\"Exception in closing \" + fis[0], e);\n          }\n        }\n      case ERROR_UNSUPPORTED:\n        // The DataNode just does not support short-circuit shared memory\n        // access, and we should stop asking.","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/shortcircuit/DfsClientShmManager.java#L158-L194","documentation":"recvFileInputStreams returned successfully but the received ancillary data contained no file descriptor (fis[0] == null): the DataNode replied SUCCESS for the shared-memory segment yet never actually passed the fd over the domain socket. The client cannot map the segment and throws IOException.","triggerScenarios":"DataNode-side failure to create or send the shm fd - descriptor limit exhausted, /dev/shm full, or a native library/protocol issue - occurring after the SUCCESS response was already sent.","commonSituations":"DataNode hitting ulimit -n ceilings; /dev/shm exhausted; client and DN Hadoop versions disagreeing on the short-circuit fd-passing protocol.","solutions":["Raise DataNode file-descriptor limits (ulimit -n) and check /dev/shm usage","Align client and DataNode Hadoop versions","Until fixed, set dfs.client.read.shortcircuit=false so reads use TCP"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (IOException e) {\n  if (e.getMessage() != null\n      && e.getMessage().contains(\"failed to pass a file descriptor\")) {\n    // DN could not send the shm fd: disable short-circuit for this client\n    conf.setBoolean(\"dfs.client.read.shortcircuit\", false);\n    recreateFileSystem();\n  } else {\n    throw e;\n  }\n}","preventionTips":["Set generous ulimit -n on DataNodes and monitor /dev/shm usage","Keep client and DN versions aligned when short-circuit is enabled"],"tags":["hdfs","short-circuit-reads","file-descriptor","data-transfer-protocol"],"backgroundTag":"file-descriptor-passing-failure","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}