AVAHI troubleshooting checklist: services not showing up—what commands/logs should I check and what are the common causes (firewall, multicast, resolved conflicts)?

When Avahi-based services don’t show up, the fix is usually in the plumbing: mDNS traffic blocked, the daemon not running on the right interface, or name resolution being intercepted by another stack (often systemd‑resolved). This checklist walks through the concrete commands, logs, and configuration points I use when debugging “why can’t I see my printer/share/app on the LAN?” on real systems.

---

At-a-Glance Checklist

Work through these roughly in order:

1. Confirm Avahi is installed and running
2. Verify the network interface is up and on the expected LAN
3. Check that service discovery works locally (browse)
4. Check that your service is actually being published
5. Inspect logs for Avahi and related components
6. Verify firewall rules for mDNS (UDP 5353) and local multicast
7. Check multicast networking (IGMP, switches, Wi‑Fi isolation)
8. *Resolve .local conflicts with systemd‑resolved and nsswitch
9. Look for hostname/service name conflicts on the LAN
10. Confirm interoperability with Bonjour/Zeroconf peers

Each section below ties that step to specific commands and common failure modes.

---

1. Confirm Avahi is installed and running

Check that the daemon is present and enabled

On most Linux distributions, Avahi ships by default.

which avahi-daemon
dpkg -l | grep avahi      # Debian/Ubuntu family
rpm -qa | grep avahi      # RHEL/Fedora family

If it’s installed, check the service:

sudo systemctl status avahi-daemon

You want:

• Loaded: yes
• Active: active (running)
• No constant crashing/restarts

If it’s not running:

sudo systemctl enable --now avahi-daemon

Common causes when this step fails:

• The package isn’t installed.
• Another mDNS implementation (e.g., older Bonjour port) is conflicting on UDP 5353.
• A recent upgrade changed D‑Bus or avahi-core behavior and the daemon crashes on startup; logs will show this (see section 5).

---

2. Verify your network interface and IP configuration

Avahi discovers services on the local link. If the host isn’t actually on the LAN you think it is, nothing else will help.

Check IP addresses and interfaces

ip addr show
ip route

Confirm:

• You have an IPv4 address on the expected interface (e.g., 192.168.x.x on eth0 or wlan0).
• There’s an appropriate default route.

Check what Avahi thinks about interfaces

avahi-browse -a -v -t

The verbose output (-v) includes the interface and protocol (IPv4/IPv6). If you see nothing at all, Avahi may have ignored the interface.

Check /etc/avahi/avahi-daemon.conf:

[server]
# Make sure this is not set to 'lo' only
allow-interfaces=eth0,wlan0
deny-interfaces=lo

If you set allow-interfaces, Avahi will ignore others; misconfigurations here are common.

Common causes when this step fails:

• Avahi is restricted to lo only or to a different interface than the one you’re using.
• You’re in a VPN namespace or container network without direct layer‑2 access to the LAN.

---

3. Check that service discovery works locally

Before worrying about your specific service, verify basic browsing.

Use avahi-browse to see what’s on the network

avahi-browse -a

This lists all services Avahi sees on the LAN.

For more detail and to avoid waiting:

avahi-browse -a -r -t

Flags:

• -a: browse for all service types.
• -r: resolve found services into hostnames/IPs.
• -t: terminate after the current browsing run instead of staying in watch mode.

If you see other devices (printers, media servers, etc.) but not your service, the problem is likely on the publishing side.

If you see nothing at all:

• No mDNS traffic is reaching the host (firewall, multicast filtering, Wi‑Fi client isolation).
• Avahi is not actually listening on the right interface.

---

4. Confirm your service is actually being published

There are two main ways services get advertised in Avahi:

• Dynamically via the D‑Bus API (most desktop apps and network daemons).
• Statically via XML files in /etc/avahi/services.

A. Check static XML service definitions

List the service files:

ls -l /etc/avahi/services

Check the syntax of a service file, e.g. /etc/avahi/services/my-service.service:

<service-group>
  <name replace-wildcards="yes">%h My Service</name>
  <service>
    <type>_myservice._tcp</type>
    <port>1234</port>
  </service>
</service-group>

Common errors:

• Invalid XML (unclosed tags, encoding issues).
• Wrong service type (typo in _http._tcp vs _htt._tcp, etc.).
• File not readable by the avahi user.

After editing:

sudo systemctl restart avahi-daemon

Then look for the service:

avahi-browse _myservice._tcp -r -t

B. Check dynamic, D‑Bus‑published services

If an application uses the D‑Bus API:

1. Ensure the application is running.

2. Use avahi-browse for the expected service type (for example, _ssh._tcp):

   avahi-browse _ssh._tcp -r -t
   

If you control the app, verify it actually registers with Avahi over D‑Bus using the documented client API (see the “How to Register Services” and “Choosing an API” docs).

Common causes when this step fails:

• Service definition not placed in /etc/avahi/services.
• XML invalid, so Avahi ignores it.
• App tries to talk to Avahi via D‑Bus but the bus name isn’t available (daemon not started or D‑Bus issue).
• Service type mismatch: you’re browsing _http._tcp but your file uses _http-alt._tcp.

---

5. Inspect logs for Avahi and related components

Logs are where you see conflicts, name collisions, and D‑Bus‑level issues.

Avahi daemon logs (systemd)

journalctl -u avahi-daemon --since "10 minutes ago"

Look for:

• Repeated restarts.
• Messages about:
  • “Name collision” or “Host name conflict”
  • “Failed to create D-Bus object”
  • “Ignoring invalid service file”
  • “Dropping packet” / “socket” errors

Older syslog-based systems

grep -i avahi /var/log/syslog
# or
grep -i avahi /var/log/messages

If you recently upgraded Avahi (e.g., to 0.8) and see references to D‑Bus/avahi-core changes, check the release notes (docs/NEWS and the relevant release page) to see if your application needs to adapt to API changes.

Common causes spotted in logs:

• Race conditions with D‑Bus object creation causing services not to be registered.
• Invalid service definitions.
• Interface binding errors (e.g., trying to bind IPv6 on an IPv4-only link).
• Hostname conflicts resulting in Avahi renaming the host (e.g., myhost.local → myhost-2.local).

---

6. Verify firewall rules for mDNS and local multicast

mDNS runs on UDP port 5353, multicast address 224.0.0.251 (IPv4) or ff02::fb (IPv6). If this is blocked, discovery fails.

Check firewalld (RHEL/Fedora, etc.)

sudo firewall-cmd --get-active-zones
sudo firewall-cmd --zone=home --list-services

Look for mdns. If it’s missing:

sudo firewall-cmd --add-service=mdns --permanent
sudo firewall-cmd --reload

Check UFW (Debian/Ubuntu)

sudo ufw status verbose

If UFW is active, allow mDNS:

sudo ufw allow in proto udp to 224.0.0.251 port 5353

iptables/nftables (manual rules)

Ensure there’s no rule dropping local multicast. For example, iptables:

sudo iptables -L -v -n | grep 224.0.0.251

Common causes when this step fails:

• Host firewall denies inbound or outbound UDP 5353.
• Strict iptables rules dropping 224.0.0.0/24 multicast.

---

7. Check multicast networking on the LAN

Even with local firewall open, the network itself can suppress multicast.

Quick on‑host checks

ip maddr show

Make sure the interface is subscribed to 224.0.0.251 (IPv4) and/or ff02::fb (IPv6).

Network-side issues to consider

• Wi‑Fi client isolation / AP isolation: many access points block clients from seeing each other, including multicast.
• Multicast filtering or snooping misconfigurations on switches.
• Multi‑subnet networks without mDNS reflectors: Avahi is LAN‑scope; it doesn’t discover across routed subnets by default.

If you suspect the network, test with two hosts in the same room on the same AP/switch, minimal firewall, and see if they can see each other via avahi-browse -a.

---

8. Fix *.local resolution and systemd‑resolved conflicts

Service discovery and hostname resolution are related but separate:

• Avahi handles service records and hostnames via mDNS.
• OS name resolution can be handled by glibc nsswitch, nss-mdns, and/or systemd-resolved.

A service may show up in avahi-browse, but ping myhost.local fails. That’s a resolver stack issue, not Avahi’s advertisement.

A. Check how name resolution is wired (nsswitch)

grep '^hosts:' /etc/nsswitch.conf

For Avahi/nss‑mdns setups you typically want something like:

hosts: files mdns_minimal [NOTFOUND=return] dns

or

hosts: files mdns dns

If mdns or mdns_minimal is missing and you rely on nss‑mdns, *.local won’t resolve via Avahi.

B. Check if systemd‑resolved is intercepting *.local

systemctl status systemd-resolved
cat /etc/systemd/resolved.conf

Look for:

[Resolve]
MulticastDNS=yes
LLMNR=no

If MulticastDNS=yes, systemd‑resolved is also doing mDNS and may conflict with how Avahi expects to integrate via nss‑mdns.

Typical options:

• Let systemd‑resolved handle mDNS and adjust expectations (Avahi for service browsing, resolved for name resolution).

• Or disable mDNS in systemd‑resolved and rely on nss-mdns + Avahi for *.local:

  [Resolve]
  MulticastDNS=no
  

Then restart:

sudo systemctl restart systemd-resolved
sudo systemctl restart avahi-daemon

Common causes when this step fails:

• ping host.local fails while avahi-browse -a shows the host: resolver chain never hands the query to Avahi’s mDNS.
• Both systemd‑resolved and nss‑mdns try to handle mDNS, leading to confusing results.

---

9. Detect hostname and service name conflicts

mDNS is designed for zero‑conf: if two hosts claim the same .local hostname, you’ll get automatic renaming. That’s helpful but confusing if you’re manually expecting host.local and Avahi chose host-2.local.

Check Avahi’s view of the local host

hostname
avahi-resolve-host-name $(hostname).local

Compare with Avahi’s logs for any messages like:

Host name conflict, retrying with myhost-2

You can also browse for your own host:

avahi-browse -a -r -t | grep $(hostname)

If you see myhost-2.local or similar, adjust scripts and clients accordingly or clean up the conflicting device on the network.

Service name conflicts

Similarly, if two devices advertise the same service name, Avahi may rewrite the service instance name (e.g., “My Printer #2”). Check for that in avahi-browse output.

Common causes when this step fails:

• Cloned VMs / images with the same hostname.
• Container hosts sharing a hostname on bridged networks.
• Old devices left on with duplicate names.

---

10. Confirm Bonjour/Zeroconf interoperability

Avahi targets Bonjour/Zeroconf compatibility. If you’re in a mixed Mac/Linux environment and services work on macOS but not on Linux, Avahi isn’t seeing or advertising something properly.

From a Linux host with Avahi

avahi-browse _afpovertcp._tcp -r -t   # Apple Filing Protocol
avahi-browse _ipp._tcp -r -t          # IPP printers
avahi-browse _smb._tcp -r -t          # SMB shares

Cross‑check with macOS:

dns-sd -B _ipps._tcp
dns-sd -B _ssh._tcp

If macOS sees services that Avahi does not:

• Re‑check firewall and multicast on the Linux host.
• Confirm avahi-daemon is bound to the correct interfaces.
• Look for errors in Avahi logs about packet drops or interface issues.

---

Putting It Together: Common Root Causes by Symptom

Symptom: No services show up at all on Linux, but other devices can see each other

Likely causes:

• avahi-daemon not running or crashing at startup.
• Firewall on Linux host blocking UDP 5353 or local multicast.
• Avahi restricted to the wrong interface in avahi-daemon.conf.
• Network segment with Wi‑Fi client isolation or multicast blocked on the switch.

Symptom: I can see other devices’ services, but my own service never appears

Likely causes:

• Misconfigured or missing XML in /etc/avahi/services.
• Application never registers via D‑Bus due to API misuse or D‑Bus errors.
• Service type mismatch between publisher and avahi-browse.

Symptom: avahi-browse shows services, but ping host.local fails

Likely causes:

• nsswitch.conf missing mdns / mdns_minimal.
• systemd‑resolved intercepting *.local without MulticastDNS enabled or correctly configured.
• nss-mdns not installed.

Symptom: Services appear with strange “‑2” / “(2)” hostnames or instance names

Likely causes:

• Hostname or service name conflict on the LAN leading Avahi to rename.
• VMs or cloned systems deployed without unique hostnames.

---

Final Notes

When you’re troubleshooting Avahi, stay close to its real interfaces:

• Use avahi-browse to validate discovery (not just application GUIs).
• Use /etc/avahi/services or the documented D‑Bus client API for publication.
• Use logs (journalctl -u avahi-daemon) and nsswitch.conf to understand where mDNS fits into name resolution.

If you run into behavior that doesn’t match this checklist, check the Avahi documentation sections on “Choosing an API,” “How to Register Services,” and “How to Browse for Services,” and consider filing an issue or joining the mailing list with the exact logs and config snippets.

Next Step

Get Started