vectordotdev/vector · error
IPv6 multicast is not supported
Error message
IPv6 multicast is not supported
What it means
The UDP socket source only implements IPv4 multicast: it calls set_multicast_loop_v4 and join_multicast_v4 with the IPv4 listen address (src/sources/socket/udp.rs:191-210). If multicast_groups is non-empty and the configured address parses to an IPv6 socket address, the SocketAddr::V6 arm panics via unimplemented!("IPv6 multicast is not supported") at udp.rs:198. The in-code comment notes IPv6 support would require std's join_multicast_v6 with an interface index, which has not been implemented.
Source
Thrown at src/sources/socket/udp.rs:198
let listenfd = ListenFd::from_env();
let socket = try_bind_udp_socket(config.address, listenfd)
.await
.map_err(|error| {
emit!(SocketBindError {
mode: SocketMode::Udp,
error,
})
})?;
if !config.multicast_groups.is_empty() {
socket.set_multicast_loop_v4(true).unwrap();
let listen_addr = match config.address() {
SocketListenAddr::SocketAddr(SocketAddr::V4(addr)) => addr,
SocketListenAddr::SocketAddr(SocketAddr::V6(_)) => {
// We could support Ipv6 multicast with the
// https://doc.rust-lang.org/std/net/struct.UdpSocket.html#method.join_multicast_v6 method
// and specifying the interface index as `0`, in order to bind all interfaces.
unimplemented!("IPv6 multicast is not supported")
}
SocketListenAddr::SystemdFd(_) => {
unimplemented!("Multicast for systemd fd sockets is not supported")
}
};
for group_addr in config.multicast_groups {
let interface = config.multicast_interface.unwrap_or(*listen_addr.ip());
socket
.join_multicast_v4(group_addr, interface)
.map_err(|error| {
emit!(SocketMulticastGroupJoinError {
error,
group_addr,
interface,
})
})?;
info!(message = "Joined multicast group.", group = %group_addr);
}View on GitHub (pinned to 711f03abce)
Solutions
- Use an IPv4 listen address for this source, e.g. address = "0.0.0.0:9999" (or a specific IPv4 unicast address), keeping the IPv4 multicast groups.
- Remove multicast_groups (and multicast_interface) if multicast membership is not actually required, then any address family works.
- Run a separate IPv4-bound UDP source solely for multicast ingestion alongside your IPv6 listener.
- If IPv6 multicast is required, patch the V6 arm to call UdpSocket::join_multicast_v6(group, interface_index 0) (as the source comment suggests) and upstream the change.
Example fix
# vector.toml — before: IPv6 listen address + multicast panics at startup [sources.udp_in] type = "socket" mode = "udp" address = "[::]:9999" multicast_groups = ["239.1.1.1:9999"] # after: IPv4 listen address (multicast path requires SocketAddr::V4) [sources.udp_in] type = "socket" mode = "udp" address = "0.0.0.0:9999" multicast_groups = ["239.1.1.1:9999"]
Defensive patterns
Strategy: validation
Validate before calling
# CI pre-deploy check: reject IPv6 listen addresses whenever multicast is configured
if grep -q 'multicast_groups' vector.toml; then
if grep -qE 'address[[:space:]]*=[[:space:]]*"\[' vector.toml; then
echo "FAIL: UDP multicast requires an IPv4 listen address (found IPv6 '[...]')"; exit 1
fi
fi Type guard
#!/usr/bin/env python3
# True only when a UDP socket config can support multicast (IPv4 explicit address)
import re, sys
cfg = open(sys.argv[1]).read()
has_mcast = re.search(r'^multicast_groups\s*=', cfg, re.M)
addr = re.search(r'^address\s*=\s*"([^"]+)"', cfg, re.M)
ok = not has_mcast or (addr and not addr.group(1).startswith("[") and not addr.group(1).startswith("systemd"))
print("multicast-ok" if ok else "multicast-unsupported") Prevention
- Pin an explicit IPv4 address (0.0.0.0:port or a specific unicast v4) on every UDP source that sets multicast_groups; never '[::]'.
- The panic occurs at source startup, not config validation, so smoke-test the exact production config (vector validate alone is not enough — actually start the topology once in CI).
- Watch for dual-stack refactors: switching a listener to IPv6 silently breaks any sibling multicast_groups setting.
- Track Vector's documented limitation: multicast_interface/multicast_groups require an IPv4, non-systemd-fd listen address.
When it happens
Trigger: A socket source with mode = "udp", a non-empty multicast_groups list, and an IPv6 listen address such as address = "[::]:9999" or address = "[::1]:9999". The panic occurs when the source task starts (right after binding), so Vector crashes at pipeline startup. The config docs for multicast_interface/multicast_groups state the listen address must be IPv4 (udp.rs:55).
Common situations: Switching a listener to "[::]" for dual-stack v4-mapped acceptance while keeping multicast_groups from an older IPv4 config; IPv6-only containers/hosts; copying an example config that used IPv6 address syntax; renaming hosts so the address literal resolves to v6.
Related errors
AI-assisted analysis of vectordotdev/vector@711f03abce (2026-08-16).
Data as JSON: /api/errors/011e0b8be8fa5e34.
Report an issue: GitHub.