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 is running but services aren’t showing up, the root cause is usually mundane: the daemon isn’t actually active, mDNS packets are being dropped by a firewall, multicast isn’t enabled on the interface you care about, or systemd-resolved/nsswitch is stealing or misrouting .local lookups. The quickest way to debug is to follow a fixed checklist: verify Avahi itself, then the network path, then name resolution.

Below is the troubleshooting path I use when someone says “Avahi is installed, but I don’t see any services.”

---

Quick Answer: Start by confirming avahi-daemon is running and not erroring (systemctl status avahi-daemon, journalctl -u avahi-daemon). Then verify you can see multicast DNS packets (tcpdump/ss on 224.0.0.251:5353), and that your firewall allows mDNS. Finally, confirm .local resolution with avahi-resolve, getent hosts, and check for conflicts with systemd-resolved and your nsswitch.conf configuration.

---

1. Quick health check: is Avahi actually running?

Check the service state

On most modern Linux systems:

systemctl status avahi-daemon.service

You want to see:

• Active: active (running)
• No rapid restarts (Start request repeated too quickly, Restarting loops)
• No obvious error like “Failed to create D-Bus object” or “No suitable network interface found”

If it’s inactive or failed:

sudo systemctl start avahi-daemon.service
sudo systemctl enable avahi-daemon.service

Then re-check the status.

Inspect Avahi logs

Use journalctl for more detail:

journalctl -u avahi-daemon.service -b

Look for messages such as:

• Interface problems

  • Ignoring interface lo
  • Ignoring loopback interface
  • Joining mDNS multicast group on interface
  • No suitable network interface found

• D-Bus/API issues

  • Disallowing new connections
  • Any error mentioning D-Bus object creation or API mismatch

• Address / hostname conflicts

  • Host name conflict, retrying with <hostname>-2
  • Name collision with <something>.local

If Avahi cannot bind to the interface or is repeatedly renaming the hostname due to conflicts, services will appear inconsistent or not show up at all.

---

2. Confirm Avahi’s view of the world (local tools)

Check which services Avahi sees and publishes

Use the CLI browser:

avahi-browse -a

You should see lines like:

+   eth0 IPv4 My Printer               _ipp._tcp          local
+   eth0 IPv4 My SSH Server            _ssh._tcp          local

If nothing appears:

• Try verbose mode:

  avahi-browse -a -v
  

• If the command hangs or errors immediately, that often indicates a D-Bus issue.

Check service publication from this host

If you expect this host to publish services (e.g., via /etc/avahi/services/*.service files), run:

avahi-browse -rt _services._dns-sd._udp

This shows which service types are being advertised. You should see the _http._tcp, _ssh._tcp, or other types you configured.

If your static services aren’t visible:

• Confirm the file exists and is readable:

  ls -l /etc/avahi/services
  cat /etc/avahi/services/your-service.service
  

• Validate XML syntax (Avahi is strict):

  • Look for missing <service-group> root tag.

  • Ensure all <name>, <type>, <port> elements exist.

  • Check the system log while reloading:

    sudo systemctl restart avahi-daemon
    journalctl -u avahi-daemon.service -b | tail -n 50
    

  Any XML parsing errors will be reported there.

---

3. Verify network and multicast basics

If Avahi thinks it’s running but no services appear from other hosts, you need to confirm multicast DNS traffic can actually flow.

Check active network interfaces Avahi is using

From the logs:

journalctl -u avahi-daemon.service -b | grep 'Joining mDNS multicast group'

You should see entries for the expected interface (e.g., eth0, wlan0). If your interface is missing:

• Ensure it is up and has an IP address:

  ip addr
  

• If the system is in a container or sandboxed environment, Avahi may not see the network stack the same way.

Confirm multicast group membership and UDP listening

Check that the host is listening on mDNS (UDP 5353) and joined to 224.0.0.251:

ss -ulnp | grep 5353      # UDP listeners
ip maddr show             # multicast group membership

You should see something like:

udp UNCONN 0    0   224.0.0.251:5353   0.0.0.0:*   users:(("avahi-daemon",pid=...,fd=...))

If nothing is listening on 5353 or no membership in 224.0.0.251:

• Re-check avahi-daemon logs for interface errors.
• Confirm no other daemon is binding 5353 (rare, but some custom stacks do).

Capture mDNS traffic with tcpdump

On the interface where you expect discovery:

sudo tcpdump -n -i eth0 port 5353

While this is running, on another machine on the same LAN, run:

avahi-browse -a

On the tcpdump host, you should see packets to/from 224.0.0.251:5353. If you see no traffic:

• The network may be blocking multicast.
• You might be on different VLANs or Wi-Fi isolation mode is enabled (common on guest networks).
• Firewalls (local or upstream) may be dropping 224.0.0.251.

If you only see outgoing queries but no incoming responses, that points to a path issue from the peer back to you (or firewall on the peer).

---

4. Firewall rules: allowing mDNS and related traffic

mDNS uses UDP 5353 to group 224.0.0.251 (IPv4) and ff02::fb (IPv6). If services aren’t visible between machines, firewall rules are a frequent culprit.

On firewalld-based systems

Check if a mDNS service exists and is enabled:

sudo firewall-cmd --get-services | grep mdns
sudo firewall-cmd --list-services

If mdns is not listed in --list-services, allow it:

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

Or add the explicit port/protocol:

sudo firewall-cmd --add-port=5353/udp --permanent
sudo firewall-cmd --reload

On nftables/iptables-based systems

Look for DROP rules on multicast or UDP 5353. For example:

sudo iptables -L -n | grep 5353
sudo ip6tables -L -n | grep 5353

If you see a drop, add an accept rule:

sudo iptables -A INPUT -p udp --dport 5353 -d 224.0.0.251 -j ACCEPT
sudo ip6tables -A INPUT -p udp --dport 5353 -d ff02::fb -j ACCEPT

Apply similar allowances in nftables if you’re using it.

Host-based firewalls on peers

Remember that both sides must allow mDNS. If you can see your own services but not peer services:

• The peer’s firewall may be blocking outgoing queries or incoming responses.
• Run the same checks on the peer.

---

5. .local name resolution: Avahi vs systemd-resolved and nsswitch

A common confusion: services may show up in avahi-browse -a, but ping host.local or ssh host.local fails. That’s not service discovery failing; it’s name resolution, typically involving nss-mdns, nsswitch.conf, and sometimes systemd-resolved.

Step 1: Test resolution through Avahi directly

Use avahi-resolve:

avahi-resolve-host-name host.local
avahi-resolve-address 192.168.1.10

If this works, Avahi is resolving names. If not, the problem is still at the service/mDNS level.

Step 2: Test system-wide resolution

Now use getent, which goes through nsswitch:

getent hosts host.local

• If avahi-resolve works but getent does not, your nsswitch.conf is not set up to use mdns/mdns4.

Typical nsswitch line (varies by distro):

hosts: files mdns4_minimal [NOTFOUND=return] dns

or

hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4

Check it:

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

If there is no mdns/mdns4 entry:

1. Install nss-mdns (package name varies: nss-mdns, libnss-mdns).
2. Edit /etc/nsswitch.conf to include mdns or mdns4 in the hosts: line.
3. Retry getent hosts host.local.

Step 3: Interactions with systemd-resolved

On systems using systemd-resolved, .local is often reserved for mDNS, but resolution may still not flow through Avahi.

Check if systemd-resolved is running:

systemctl status systemd-resolved.service
resolvectl status

Typical conflict patterns:

• .local is being handled by systemd-resolved with its own mDNS implementation, while Avahi is also trying to handle mDNS.
• The system’s resolv.conf points to systemd-resolved, but nsswitch isn’t using mdns*, so mDNS never reaches Avahi.

Common approaches:

• If you want Avahi + nss-mdns to handle .local:

  • Ensure mdns4_minimal is in nsswitch.conf.
  • Confirm systemd-resolved isn’t configured to override .local namespace in a conflicting way (check resolvectl domain, resolvectl mdns).

• If you prefer systemd-resolved to handle mDNS:

  • You can still run Avahi for service discovery, but accept that .local host resolution may not go via Avahi. Use avahi-browse for services and let systemd-resolved answer hostnames.

In either case, align your expectations: services not showing in avahi-browse is an Avahi issue; .local not resolving in ping is usually a resolver configuration issue.

---

6. Common root causes and how to pinpoint them

6.1 Avahi daemon not running or misconfigured

Symptoms:

• systemctl status avahi-daemon shows inactive or failed.
• avahi-browse -a errors with D-Bus connection issues.

Checks:

• systemctl status avahi-daemon
• journalctl -u avahi-daemon.service -b

Fix:

• Start/enable the service.
• Resolve D-Bus or configuration errors shown in logs.

---

6.2 Firewall blocking mDNS traffic

Symptoms:

• avahi-browse -a shows only local services, or none between hosts.
• tcpdump shows outbound queries but no inbound responses.

Checks:

• tcpdump -n -i <iface> port 5353
• firewall-cmd --list-services or iptables -L -n | grep 5353
• ss -ulnp | grep 5353

Fix:

• Allow UDP 5353 for 224.0.0.251 / ff02::fb in local firewall.
• Ensure upstream/network firewalls aren’t filtering multicast.

---

6.3 Multicast disabled or network-level isolation

Symptoms:

• No mDNS traffic visible in tcpdump at all.
• Devices on the same physical network but different VLANs can’t see each other’s services.

Checks:

• ip maddr show
• tcpdump -n -i <iface> port 5353

Fix:

• Enable multicast support on the network.
• Ensure no client isolation/guest Wi-Fi segmentation is in place for devices that need to discover each other.

---

6.4 .local resolution conflicts (systemd-resolved, nsswitch)

Symptoms:

• avahi-browse -a shows services, but host.local fails to resolve with ping/ssh.
• avahi-resolve-host-name host.local works, but getent hosts host.local fails.

Checks:

• avahi-resolve-host-name host.local
• getent hosts host.local
• grep '^hosts:' /etc/nsswitch.conf
• systemctl status systemd-resolved
• resolvectl status

Fix:

• Install nss-mdns and add mdns4_minimal/mdns to nsswitch.conf.
• Decide whether Avahi or systemd-resolved should be authoritative for .local and configure accordingly.

---

6.5 Static service file issues (/etc/avahi/services)

Symptoms:

• Expected local service does not show up in avahi-browse -a.
• Restarting avahi-daemon logs XML parsing errors.

Checks:

• ls -l /etc/avahi/services
• cat /etc/avahi/services/*.service
• journalctl -u avahi-daemon.service -b | tail -n 50

Fix:

• Correct XML syntax and required elements.
• Ensure files are readable by the daemon.
• Restart avahi-daemon.

---

6.6 D-Bus / client integration issues

If your application uses the D-Bus API to register/browse services and they’re not appearing:

Symptoms:

• Your app logs D-Bus errors.
• Services appear when configured via XML in /etc/avahi/services but not when published dynamically by your app.

Checks:

• Application logs for D-Bus connection failures or API errors.

• Avahi logs for “Client died”, “Disallowing new connections”, or “racing signals” type messages.

• Confirm the D-Bus system bus is running:

  systemctl status dbus
  

Fix:

• Ensure your client handles daemon restarts (see Avahi docs on “How to Write a Client That Can Deal with Daemon Restarts”).
• Confirm you’re using the correct D-Bus interface and API version for the Avahi version you’re running.
• File an issue or join the mailing list if you suspect a regression after upgrading (include Avahi version, D-Bus error, and logs).

---

7. A practical “minimal working test”

If you want a simple, repeatable check across two Linux machines on the same LAN:

On machine A

1. Ensure Avahi is running:

   sudo systemctl start avahi-daemon
   

2. Create a simple HTTP service:

   echo '<service-group>
     <name replace-wildcards="yes">%h Test HTTP</name>
     <service>
       <type>_http._tcp</type>
       <port>8080</port>
     </service>
   </service-group>' | sudo tee /etc/avahi/services/test-http.service
   sudo systemctl restart avahi-daemon
   

3. Confirm Avahi sees it locally:

   avahi-browse -rt _http._tcp
   

On machine B

1. Confirm Avahi is running:

   sudo systemctl start avahi-daemon
   

2. Try to see the service:

   avahi-browse -rt _http._tcp
   

If this fails, step through:

• tcpdump on both sides (port 5353)
• Firewall rules on both machines
• Multicast membership and VLAN/guest network constraints

Once this minimal case works, you can layer your real services and resolver configuration on top.

---

Final checklist summary

When services aren’t showing up with Avahi, run through:

1. Daemon health

   • systemctl status avahi-daemon.service
   • journalctl -u avahi-daemon.service -b

2. Local service visibility

   • avahi-browse -a
   • avahi-browse -rt _services._dns-sd._udp
   • Check /etc/avahi/services/*.service if using static definitions.

3. Network/multicast path

   • ip addr, ip maddr show
   • ss -ulnp | grep 5353
   • sudo tcpdump -n -i <iface> port 5353

4. Firewall

   • firewall-cmd --list-services or iptables -L -n | grep 5353
   • Open UDP 5353 to 224.0.0.251 / ff02::fb as needed.

5. Name resolution (.local)

   • avahi-resolve-host-name host.local
   • getent hosts host.local
   • grep '^hosts:' /etc/nsswitch.conf
   • systemctl status systemd-resolved, resolvectl status

6. Client/D-Bus integration

   • Application logs
   • Avahi logs referencing clients and D-Bus
   • Ensure clients handle daemon restarts cleanly.

If you isolate an issue that looks like an Avahi bug rather than configuration—especially after an upgrade—capture the exact commands, logs, Avahi version, and distro details, then file an issue or send a report to the mailing list so it can be reproduced and fixed.

Next Step

Get Started