sgl-project/sglang · error · RuntimeError

received truncated fd header: {len(data)} < {_FD_INDEX_STRUC

Error message

received truncated fd header: {len(data)} < {_FD_INDEX_STRUCT.size}

What it means

_recv_fd expected a fixed-size fd-index header but recvmsg returned fewer bytes — the peer sent a truncated or malformed FD message over the SCM_RIGHTS channel.

Source

Thrown at python/sglang/srt/weight_cache/transport.py:44

def _send_fd(sock: socket.socket, fd: int, index: int) -> None:
    payload = _FD_INDEX_STRUCT.pack(index)
    fds = array.array("i", [int(fd)])
    sent = sock.sendmsg(
        [payload], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds.tobytes())]
    )
    if sent != len(payload):
        raise RuntimeError(f"sendmsg sent {sent} bytes, expected {len(payload)}")


def _recv_fd(sock: socket.socket) -> Tuple[int, int]:
    fd_item_size = array.array("i").itemsize
    data, ancdata, _, _ = sock.recvmsg(
        _FD_INDEX_STRUCT.size, socket.CMSG_SPACE(fd_item_size)
    )
    if len(data) != _FD_INDEX_STRUCT.size:
        raise RuntimeError(
            f"received truncated fd header: {len(data)} < {_FD_INDEX_STRUCT.size}"
        )
    index = _FD_INDEX_STRUCT.unpack(data)[0]
    fds = array.array("i")
    for level, cmsg_type, cmsg_data in ancdata:
        if level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            fds.frombytes(cmsg_data[: len(cmsg_data) - (len(cmsg_data) % fd_item_size)])
    if len(fds) != 1:
        for fd in fds:
            os.close(fd)
        raise RuntimeError(f"expected one fd, got {len(fds)}")
    return int(index), int(fds[0])


class WeightCacheTransportBackend(ABC):
    name: str

    @abstractmethod

View on GitHub (pinned to 0132848349)

Solutions

1. Restart daemon and client with matching sglang versions
2. Check daemon logs for the underlying crash
3. Report if it persists with matching versions (protocol bug)

try:
    idx, fd = _recv_fd(sock)
except RuntimeError as e:
    if 'truncated' in str(e): abort_transport()

When it happens

Trigger: Peer closed or sent garbage instead of the packed fd-index struct; version mismatch between transport endpoints.

Common situations: Daemon crash mid FD handoff; mixing sglang versions on client and daemon sides of the VMM/torch IPC transport.

Related errors

• expected one fd, got {len(fds)}
• duplicate fd for {key}
• sendmsg sent {sent} bytes, expected {len(payload)}
• --mm-feature-transport=cuda_ipc requires NVIDIA CUDA.
• --decoupled-spec-bind-endpoint, --decoupled-spec-connect-end

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/b209c6c29e41b93f. Report an issue: GitHub.