udp: report an unresolvable bind hostname as a getaddrinfo error

[robobun]

Problem

• Bun.udpSocket({ hostname }) with a hostname that does not resolve rejects with an errno-shaped error: bind ENOENT <host> on glibc, bind ESRCH <host> with no resolver reachable, bind ENOEXEC <host> on macOS. Node reports getaddrinfo ENOTFOUND <host>.
• The name depends on which EAI_* value getaddrinfo returned and on the platform's sign for it, so one failure is reported differently per OS and per resolver state.
• Cause: the UDP bind path in usockets returned the getaddrinfo code through the out-parameter every other failure uses for an errno, and the caller named it as whatever errno shares that number.

Fix

• The getaddrinfo code comes back through a separate dns_error out-parameter and the errno parameter stays 0 on that path, so a resolver code can no longer be read as an errno.
• Bun.udpSocket maps it the way Bun.connect and fetch() already map a failed lookup (Report DNS lookup failures from fetch() and Bun.connect as ENOTFOUND #32990; Report an unresolvable listen hostname as a getaddrinfo error #37690 does the same for Bun.listen / Bun.serve) and throws getaddrinfo ENOTFOUND <host> with syscall and hostname set, as Node does. Real bind failures (bind EADDRINUSE <host> with .address) and { fd } adoption are unchanged.
• Other callers: quic ignores the new parameter, except node:quic, which uses dns_error as its close status when the errno is 0. node:dgram resolves through dns.lookup first, so it only reaches this branch via a custom lookup returning a non-IP string.
• Verification: a new test fails on the released build with the bind ENOENT shape and passes with this change; a second pins the EADDRINUSE shape. CI is green on glibc, musl, macOS and Windows. The numeric errno still differs from Node and is deliberately not asserted.

Background

• getaddrinfo(3) returns its own EAI_* codes, not errno values; they are negative on glibc (EAI_NONAME = -2) and positive on macOS (EAI_NONAME = 8), so the same integer in the errno channel names a different errno on each platform.
• usockets (packages/bun-usockets) is the C layer under Bun's sockets. It reports failures to Rust through int * out-parameters, and Rust turns an errno into the JS code string via SystemErrno.
• c_ares::Error::init_eai is Bun's shared mapping from a raw getaddrinfo code to the lookup error it reports elsewhere (ENOTFOUND and friends; on Windows it folds WSA codes into ENOTFOUND). A separate dns_error channel fed into it is how Bun.connect and fetch() already report lookup failures.

Original description

Repro

const host = Buffer.alloc(64, "a").toString() + ".com"; // 64-byte label: getaddrinfo rejects it locally
try {
  await Bun.udpSocket({ hostname: host, port: 0 });
} catch (e) {
  console.log(e.code, e.syscall, e.hostname, e.message);
}

Before (Linux, 1.4.0 and main):

ENOENT bind undefined bind ENOENT aaaa....com

The code depends on which EAI_* value getaddrinfo returned: EAI_NONAME (-2 on glibc) comes out as ENOENT, EAI_AGAIN (-3, e.g. no resolver reachable) as bind ESRCH <host>. On macOS the constants are positive (EAI_NONAME = 8), so the negated value is abs()ed back into ENOEXEC.

After:

ENOTFOUND getaddrinfo aaaa....com getaddrinfo ENOTFOUND aaaa....com

Cause

bsd_create_udp_socket() in packages/bun-usockets/src/bsd.c did *err = -gai_result; when getaddrinfo() failed. Every other write to err in that function is an errno, and the consumer (UDPSocket::udp_socket in src/runtime/socket/udp_socket.rs) maps it with SystemErrno::init and reports syscall: "bind", so a resolver return code was being named as whatever errno shares its number.

Fix

bsd_create_udp_socket() / us_create_udp_socket() gain a separate int *dns_error out-parameter that receives the raw getaddrinfo() return code (err stays 0 on that path), threaded through uws::udp::Socket::create. udp_socket.rs maps it with c_ares::Error::init_eai and builds the error with system_error_with_syscall_and_hostname(.., "getaddrinfo", hostname). The errno path (bind EADDRINUSE <host> with .address, open <code> for { fd } adoption) is unchanged.

Why this shape: it is the one Bun already uses for a failed lookup everywhere else. Bun.connect and fetch() carry the raw code on a separate dns_error channel and map it with init_eai (#32990), #37690 does the same for Bun.listen / Bun.serve, and this PR is the UDP bind counterpart. It is also what Node reports for the same input: dgram.createSocket("udp4").bind({ address: host }) on Node 26.3 emits getaddrinfo ENOTFOUND <host> with code: "ENOTFOUND", syscall: "getaddrinfo", hostname set and no address, both for the 64-byte label and for name-shaped strings such as "256.256.256.256" (getaddrinfo treats those as names too, so they take the same new branch). The remaining difference from Node is the numeric errno (Node uses the libuv code, Bun the same c-ares value Bun.connect / fetch() report), which the tests deliberately do not pin. Only the errno path is platform-specific on purpose: on Windows init_eai folds the raw WSA codes into ENOTFOUND, exactly as it already does for Bun.connect / fetch().

node:dgram is not affected in practice: with the default lookup it resolves through dns.lookup and hands Bun.udpSocket an IP, so this branch is only reachable through a custom lookup that yields a non-IP string, and that case now gets the resolver error instead of the mis-named errno.

Other us_create_udp_socket callers: the three in quic.c never read the error and pass NULL; node:quic's ensure_bound() always binds an IP literal, and now falls back to dns_error for the close status so a (memory/system) resolver failure there still reports a nonzero status instead of 0.

Not changed here: the UDP connect path already reports a resolver error (connect ENOTFOUND <host>, name DNSException); the existing synchronous throw vs. rejection behaviour is #35217's subject.

Verification

New tests in test/js/bun/udp/udp_socket.test.ts (bind failure errors): the unresolvable-hostname case fails on the released build with the bind ENOENT shape above and passes with this change; the second test pins the bind EADDRINUSE 127.0.0.1 / .address shape of a real bind failure.

bun bd test test/js/bun/udp/        # 272 pass
test/js/node/test/parallel/test-dgram-{error-message-address,bind-error-repeat,bind-fd-error,bind,custom-lookup}.js
test/js/node/test/parallel/test-quic-endpoint-bind{,-failure}.mjs

CI is green on every lane, so the ENOTFOUND expectation holds for the libc getaddrinfo on macOS, Windows and musl as well as glibc.

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 1 minute

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b37245e6-9bb6-4723-848b-bc3c9dc9d1e3

📥 Commits

Reviewing files that changed from the base of the PR and between e7abdf7 and 780fddc.

📒 Files selected for processing (9)

• packages/bun-usockets/src/bsd.c
• packages/bun-usockets/src/internal/networking/bsd.h
• packages/bun-usockets/src/libusockets.h
• packages/bun-usockets/src/quic.c
• packages/bun-usockets/src/udp.c
• src/runtime/node/quic/endpoint.rs
• src/runtime/socket/udp_socket.rs
• src/uws_sys/udp.rs
• test/js/bun/udp/udp_socket.test.ts

---

_{Comment @coderabbitai help to get the list of available commands.}

[robobun]

^{Updated 6:47 PM PT - Aug 11th, 2026}

✅ @robobun, your commit 780fddc85c75d58a3191ac5ea740b34bc4df6dac passed in Build #92716! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 37707

That installs a local version of the PR into your bun-37707 executable, so you can run:

bun-37707 --bun

[robobun]

Status

Reproduced on the released build (1.4.0) and on main: Bun.udpSocket({ hostname: "<64-byte label>.com" }) rejects with bind ENOENT <host> (EAI_NONAME negated into errno 2); with no resolver reachable it is bind ESRCH <host> instead. With this PR both report getaddrinfo ENOTFOUND <host> / getaddrinfo ETIMEOUT <host> with syscall: "getaddrinfo" and hostname set, the shape Bun.connect and fetch() already use (and #37690 adds for Bun.listen), and the shape Node 26 emits from dgram bind() for the same input.

Test: test/js/bun/udp/udp_socket.test.ts > bind failure errors (fails on the released build, passes with this branch).

CI build 92716 is green on every lane (the only retries were unrelated install/napi tests). Review turned up nothing that needs a code change. Ready for a maintainer.

[claude]

I reviewed this PR and didn't find any bugs. Because it threads an FFI signature change across the C/Rust boundary (bsd.c → udp.c → uws_sys → two Rust callers) and changes user-visible error shapes, a human look would still be worthwhile.

What was reviewed:

• Verified every bsd_create_udp_socket / us_create_udp_socket / uws::udp::Socket::create call site is updated for the new dns_error out-param (quic.c passes NULL, endpoint.rs and udp_socket.rs pass a local).
• Checked init_eai(0) returns None on all platforms and the Windows arm's _ => ENOTFOUND catch-all handles raw WSA getaddrinfo codes; the .filter(|_| dns_error != 0) is redundant but harmless.
• Confirmed the drop(hostname_z) removal is required (now read in the new error branch) and ZBox::as_bytes() excludes the NUL.
• The new tests use a 64-byte DNS label (no network round-trip) and bind without reuse flags, so both should be hermetic.

Extended reasoning...

Overview

This PR fixes UDP bind error reporting when getaddrinfo() fails: previously the raw EAI_* code was written to the errno out-param and misreported as bind ENOENT/bind ESRCH/bind ENOEXEC depending on platform. The fix adds a separate int *dns_error out-parameter to bsd_create_udp_socket / us_create_udp_socket, threads it through the Rust FFI wrapper, and has UDPSocket::udp_socket map it via c_ares::Error::init_eai + system_error_with_syscall_and_hostname — the exact pattern already used by Bun.connect, fetch(), and (per #37690) Bun.listen. Nine files touched: 5 in bun-usockets (C), 3 Rust files, plus tests.

Security risks

None identified. This is error-message shaping; no new input parsing, no changes to what gets bound or resolved. The unresolvable-hostname test uses an RFC-1035-illegal label so resolution fails locally without touching the network.

Level of scrutiny

Medium. The change is mechanically straightforward and follows a precedent set twice before in this codebase, but it is an FFI ABI change coordinated across C headers, C implementations, and Rust extern declarations — a mismatch here would be a silent miscompile. I grepped every caller of both functions and the Rust wrapper and confirmed all are updated with matching arity/position. The quic.c callers correctly pass NULL (they bind IP literals or ignore the error), and endpoint.rs sensibly falls back to dns_error for the close status so a resolver-level failure there doesn't report status 0.

Other factors

• The removed drop(hostname_z) is intentional: the new DNS-error branch reads hostname_z.as_bytes() to populate the hostname field, so it must survive past Socket::create. ZBox::as_bytes() excludes the trailing NUL, so the reported hostname is clean.
• init_eai(0) returns None on both the Windows and POSIX arms, so the .filter(|_| dns_error != 0) is belt-and-suspenders; the fd-adoption path (which never touches dns_error) can't accidentally take the DNS branch.
• Tests cover both the new resolver-error shape and pin the unchanged bind EADDRINUSE errno shape. The EADDRINUSE test binds two sockets to the same 127.0.0.1:port with no reuse flags, which should fail deterministically; if it turns out flaky on a particular CI lane that would be worth a second look, but it looks sound.
• Given the cross-language ABI coordination and the user-visible behavior change, deferring to a human reviewer rather than auto-approving.

[robobun]

Heads-up from #40986, which adds a bun_dns::is_valid_hostname check to Bun.udpSocket (bind and the connect option), Bun.serve and Bun.listen before the synchronous getaddrinfo (the bind-side counterpart of #40970).

If #40986 lands first, the 64-byte label this test uses is answered in-process with getaddrinfo ENOTFOUND <host> and never reaches the new dns_error out-param. The assertion still passes, but it no longer fails without this change. A well-formed name that glibc rejects locally keeps the test hermetic on Linux: a*b.com, a/b.com, -a.com and ünicode.com all return EAI_NONAME without a query, and is_valid_hostname accepts all four. macOS and Windows need a check in CI.

The two changes are independent otherwise: #40986 does not touch bsd.c, udp.c or udp.rs, and the nxdomain.invalid case is still this PR's.