{"record":{"id":"f8fd02dc615031dc","repo":"block/buzz","slug":"buzz-uds-path-uds-path-exists-but-is-not-a-socke","errorCode":null,"errorMessage":"BUZZ_UDS_PATH {uds_path} exists but is not a socket","messagePattern":"BUZZ_UDS_PATH (.+?) exists but is not a socket","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/buzz-relay/src/main.rs","lineNumber":1343,"sourceCode":"            \"Signalled restart close to all live WebSocket connections\"\n        );\n        hard_shutdown_abort\n    });\n\n    let tcp_listener = tokio::net::TcpListener::bind(&config.bind_addr)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to bind {}: {e}\", config.bind_addr))?;\n    info!(addr = %config.bind_addr, \"buzz-relay TCP listening\");\n\n    #[cfg(unix)]\n    if let Some(ref uds_path) = config.uds_path {\n        use std::os::unix::fs::FileTypeExt as _;\n        match std::fs::symlink_metadata(uds_path) {\n            Ok(meta) if meta.file_type().is_socket() => {\n                let _ = std::fs::remove_file(uds_path);\n            }\n            Ok(_) => {\n                return Err(anyhow::anyhow!(\n                    \"BUZZ_UDS_PATH {uds_path} exists but is not a socket\"\n                ));\n            }\n            Err(_) => {}\n        }\n        let uds_listener = tokio::net::UnixListener::bind(uds_path)\n            .map_err(|e| anyhow::anyhow!(\"Failed to bind UDS {uds_path}: {e}\"))?;\n        info!(path = %uds_path, \"buzz-relay UDS listening\");\n\n        let router_uds = router.clone();\n        let mut uds_rx = shutdown_tx.subscribe();\n        let uds_handle = tokio::spawn(async move {\n            axum::serve(uds_listener, router_uds.into_make_service())\n                .with_graceful_shutdown(async move {\n                    uds_rx.changed().await.ok();\n                })\n                .await\n                .ok();","sourceCodeStart":1325,"sourceCodeEnd":1361,"githubUrl":"https://github.com/block/buzz/blob/f956e6fe06a76e50cbd8fba1a162482e752e7f1a/crates/buzz-relay/src/main.rs#L1325-L1361","documentation":"When BUZZ_UDS_PATH is set on unix, serve() stats the path with std::fs::symlink_metadata before binding. A stale socket file is auto-removed, but any other existing entry — regular file, directory, FIFO, or a symlink (symlink_metadata does not follow links, so even a symlink to a socket fails the is_socket() check) — is fatal with this error. The guard exists so the relay never deletes operator data just to create its socket.","triggerScenarios":"BUZZ_UDS_PATH pointing at an existing regular file (pidfile, log), a directory, or a symlink. The classic container case: bind-mounting a host path over the socket file path makes Docker create a directory exactly where the relay wants to bind.","commonSituations":"Kubernetes/Docker volumes mounted at the socket path materializing as directories; sharing /run paths with other daemons; leftover artifacts from another program using the same path; operators pre-creating the file for permission reasons.","solutions":["Inspect the path: ls -la <path> and file <path> to see what it actually is.","If disposable, remove it (rm for files, rmdir for empty dirs) or repoint BUZZ_UDS_PATH to a clean path.","In containers, mount the parent directory (not the socket file path) so the relay can create a normal socket inside it.","If a symlink was intentional, remove it — the relay will neither follow nor replace symlinks."],"exampleFix":"# before: Error: BUZZ_UDS_PATH /run/buzz/buzz.sock exists but is not a socket\n# (a directory was created by a file bind-mount)\ndocker run -v /run/buzz/buzz.sock:/run/buzz/buzz.sock ...\n\n# after: mount the parent directory instead\ndocker run -v /run/buzz:/run/buzz ...","handlingStrategy":"validation","validationCode":"// Before starting the relay, verify the UDS path is absent or a socket:\nfn uds_path_clear(path: &std::path::Path) -> bool {\n    match std::fs::symlink_metadata(path) {\n        Err(_) => true,\n        Ok(meta) => meta.file_type().is_socket(),\n    }\n}\n\nif let Some(uds) = std::env::var(\"BUZZ_UDS_PATH\").ok() {\n    assert!(uds_path_clear(std::path::Path::new(&uds)),\n        \"{uds} exists and is not a socket — remove it or repoint BUZZ_UDS_PATH\");\n}","typeGuard":"use std::os::unix::fs::FileTypeExt as _;\n\nfn uds_conflict_kind(path: &std::path::Path) -> Option<&'static str> {\n    match std::fs::symlink_metadata(path) {\n        Ok(m) if m.is_dir() => Some(\"directory\"),\n        Ok(m) if m.file_type().is_symlink() => Some(\"symlink\"),\n        Ok(m) if m.file_type().is_socket() => None,\n        Ok(_) => Some(\"regular-file\"),\n        Err(_) => None,\n    }\n}","tryCatchPattern":null,"preventionTips":["Mount the socket's parent directory in containers, never the socket file path itself","Reserve the UDS path exclusively for the relay — no pidfiles or logs at the same location","Add an entrypoint/init-container check that the path is absent or a socket before start"],"tags":["rust","unix","unix-domain-socket","filesystem","docker","startup"],"backgroundTag":"unix-socket-bind-failed","analyzedSha":"f956e6fe06a76e50cbd8fba1a162482e752e7f1a","analyzedAt":"2026-08-16T22:11:40.750Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}