vectordotdev/vector · error

Failed to bind to datagram socket

Error message

Failed to bind to datagram socket

What it means

`UnixDatagram::bind(&listen_path)` failed and this `expect("Failed to bind to datagram socket")` panics the source task. Typical OS causes: the socket path already exists (stale socket file from an unclean shutdown), the path exceeds the ~107-byte unix socket address limit (sun_path), the parent directory does not exist, or the process lacks write permission on the directory.

Source

Thrown at src/sources/util/unix_datagram.rs:42

        util::{change_socket_permissions, unix::UNNAMED_SOCKET_HOST},
    },
};

/// Returns a `Source` object corresponding to a Unix domain datagram socket.
/// Passing in different functions for `decoder` and `handle_events` can allow
/// for different source-specific logic (such as decoding syslog messages in the
/// syslog source).
pub fn build_unix_datagram_source(
    listen_path: PathBuf,
    socket_file_mode: Option<u32>,
    max_length: usize,
    decoder: Decoder,
    handle_events: impl Fn(&mut [Event], Option<Bytes>) + Clone + Send + Sync + 'static,
    shutdown: ShutdownSignal,
    out: SourceSender,
) -> crate::Result<Source> {
    Ok(Box::pin(async move {
        let socket = UnixDatagram::bind(&listen_path).expect("Failed to bind to datagram socket");
        info!(message = "Listening.", path = ?listen_path, r#type = "unix_datagram");

        change_socket_permissions(&listen_path, socket_file_mode)
            .expect("Failed to set socket permissions");

        let result = listen(socket, max_length, decoder, shutdown, handle_events, out).await;

        // Delete socket file.
        if let Err(error) = remove_file(&listen_path) {
            emit!(UnixSocketFileDeleteError {
                path: &listen_path,
                error
            });
        }

        result
    }))
}

View on GitHub (pinned to 3708c39b12)

Solutions

1. Remove the stale socket file before start (systemd `ExecStartPre=/usr/bin/rm -f <path>` or an init script rm)
2. Shorten socket_path to well under 108 bytes total
3. Ensure the parent directory exists and is writable by Vector's user
4. Ensure only one Vector instance binds the same socket path

Example fix

# before
[Service]
ExecStart=/usr/bin/vector --config /etc/vector/vector.yaml
# after
[Service]
ExecStartPre=/usr/bin/rm -f /var/run/vector/syslog.sock
ExecStart=/usr/bin/vector --config /etc/vector/vector.yaml

# shell: pre-start checks for a unix_datagram socket
SOCKET=/var/run/vector/syslog.sock
[ -e "$SOCKET" ] && rm -f "$SOCKET"
[ ${#SOCKET} -lt 108 ] || { echo "socket path too long"; exit 1; }
mkdir -p "$(dirname "$SOCKET")"

When it happens

Trigger: Starting a unix_datagram source (e.g. syslog over unix datagram) while socket_path already exists as a file; socket_path longer than 107 bytes; parent dir missing or not writable by the Vector user.

Common situations: Vector killed with SIGKILL (OOM, kill -9) leaving the socket file behind; deeply nested socket paths; running as non-root with socket_path under /run without systemd socket activation; two Vector instances configured with the same path.

Related errors

• Failed to bind to listener socket at path: {}. Err: {}
• valid message key
• Failed to set socket permissions
• Failed to set socket permissions
• path and query should never fail to parse

AI-assisted analysis of vectordotdev/vector@3708c39b12 (2026-08-20). Data as JSON: /api/errors/bfd7e7749310680d. Report an issue: GitHub.