Resolving 'Name in Use' Error for homedock.local

The homedock.local feature uses the Multicast DNS (mDNS) protocol to make your HomeDock OS instance easily accessible on your local network. A fundamental rule of mDNS is that every name on the network must be unique. If HomeDock OS detects that another device is already using the homedock.local name, it will fail to start the service to prevent network conflicts, resulting in the following error:

_{! The name 'homedock.local' is already in use on your local network.}

This guide explains why this NonUniqueNameException occurs and how to resolve it.

Why Does This Issue Occur?

mDNS works by having each device “claim” a name. Before claiming homedock.local, HomeDock OS sends a “probe” message to the network, asking, “Is anyone else using this name?” If another device responds, or if a previous session of HomeDock OS did not shut down cleanly, the name is considered “in use,” and the new instance will not register it.

This is a built-in safety feature of the mDNS protocol to ensure network stability.

---

When Does It Happen?

This error typically arises in one of these common scenarios:

1. Another HomeDock OS Instance is Running: You may have another device (like a Raspberry Pi, a server, or another computer) on the same network that is also running HomeDock OS with the homedock.local feature enabled.

2. Improper Shutdown: If HomeDock OS was previously running and was terminated abruptly (e.g., due to a power outage, a system crash, or being force-quit with Ctrl+C without proper cleanup), it may not have had a chance to “unregister” its name from the network. Other devices on the network will remember the old instance for a short period.

3. Network Caching (TTL): When a device announces a name via mDNS, it comes with a Time-To-Live (TTL). Even after an improper shutdown, other devices will hold onto the old homedock.local entry in their cache until this TTL expires, which typically takes around 2 minutes.

---

How to Resolve the Issue?

Resolving this issue is usually straightforward. Follow these steps in order:

1. Check for Other Instances

First, ensure that no other copies of HomeDock OS are running on your local network with the same feature enabled. If you find one, either disable the homedock.local feature on it or shut it down.

2. Wait for the Network Cache to Clear

If you are certain no other instances are running, the most likely cause is an improper shutdown. The simplest solution is to wait for 2-3 minutes. This gives the network’s mDNS cache time to expire. After waiting, try starting HomeDock OS again.

3. Restart Your Network Router (Last Resort)

In rare cases, a network router with a “sticky” or poorly implemented mDNS/DNS cache might hold onto the name for longer. Restarting your main network router can help clear its cache and resolve the conflict.

---

What if I Don’t Need homedock.local?

If accessing your instance via its direct IP address is sufficient for your needs, you can simply disable this feature. This will prevent the error from occurring.

You can disable it in HomeDock OS Settings or by editing the configuration file and setting the local_dns variable to false.