What causes "Multicast for systemd fd sockets is not supported" in vectordotdev/vector?

Remove multicast_groups and multicast_interface from the socket-activation source and let the systemd socket unit handle group membership instead (IPMulticast= in the .socket unit, if available on your systemd version).

vectordotdev/vector · error

Multicast for systemd fd sockets is not supported

Error message

Multicast for systemd fd sockets is not supported

What it means

When the UDP socket source receives its socket via systemd socket activation (address = "systemd" or "systemd#N", parsed in src/sources/util/net/mod.rs:113-125), Vector only gets an fd offset, not a bindable IPv4 address. The multicast setup path needs an IPv4 listen address to pass as the interface to join_multicast_v4, so the SystemdFd arm panics via unimplemented!("Multicast for systemd fd sockets is not supported") at src/sources/socket/udp.rs:201 whenever multicast_groups is non-empty. The restriction is explicitly noted in the source's config docs (udp.rs:55).

Source

Thrown at src/sources/socket/udp.rs:201

            .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);
            }
        }

        if let Some(receive_buffer_bytes) = config.receive_buffer_bytes

View on GitHub (pinned to 711f03abce)

Solutions

Remove multicast_groups and multicast_interface from the socket-activation source and let the systemd socket unit handle group membership instead (IPMulticast= in the .socket unit, if available on your systemd version).
Drop socket activation for this source and bind an explicit IPv4 address (address = "0.0.0.0:9999") so Vector owns the socket and can join groups itself, using CAP_NET_RAW/ambient capabilities if the port or membership needs privileges.
Patch the SystemdFd arm in src/sources/socket/udp.rs to derive the IPv4 interface from socket.local_addr() (an owned fd knows its local address) and upstream the change.
File/track an upstream issue for systemd-fd multicast support before building packaging around this combination.

Example fix

# vector.toml — before: systemd fd + multicast panics (no IPv4 addr for join_multicast_v4)
[sources.udp_in]
type = "socket"
mode = "udp"
address = "systemd"
multicast_groups = ["239.1.1.1:9999"]

# after: direct IPv4 bind so Vector performs the join itself
[sources.udp_in]
type = "socket"
mode = "udp"
address = "0.0.0.0:9999"
multicast_groups = ["239.1.1.1:9999"]

Defensive patterns

Strategy: fallback

Validate before calling

# CI pre-deploy check: reject systemd-fd listen addresses whenever multicast is configured
if grep -q 'multicast_groups' vector.toml; then
  if grep -qE 'address[[:space:]]*=[[:space:]]*"systemd(#?[0-9]+)?"' vector.toml; then
    echo "FAIL: multicast_groups cannot be combined with address = \"systemd\""; exit 1
  fi
fi

Prevention

Treat address = "systemd"/"systemd#N" and multicast_groups as mutually exclusive in config templates and reviews.
If multicast ingestion is required, prefer a directly bound IPv4 address with capabilities over socket activation, or handle group membership in the systemd socket unit.
When adopting systemd socket activation for an existing source, audit the config block for multicast_groups/multicast_interface leftovers before restart.
Start the topology once in a staging unit (not just vector validate) because this panic fires at source startup, after config validation passes.

When it happens

Trigger: A Vector unit managed by systemd with a socket unit (ListenDatagram=...) passing fds, a socket source with mode = "udp" and address = "systemd" (or "systemd#2" for multiple fds), combined with any non-empty multicast_groups. The panic occurs at source startup when the multicast setup runs, taking the pipeline down immediately after socket handoff.

Common situations: Debian/RPM packages or hardening setups that use socket activation for privileged ports, later augmented with multicast_groups for discovery protocols (mDNS-style ingest, statsd multicast); test harnesses that pass systemd fds; configs migrated from a directly-bound IPv4 address to socket activation without dropping the multicast block.

Related errors

AI-assisted analysis of vectordotdev/vector@711f03abce (2026-08-16). Data as JSON: /api/errors/8539ba34c5577d7c. Report an issue: GitHub.