How to Access and Troubleshoot Your Home Assistant Local URL

The default local URL for a standard Home Assistant installation is http://homeassistant.local:8123.

This address serves as the primary gateway for users to access their smart home dashboard, configure integrations, and manage automations while connected to the same home Wi-Fi or Ethernet network. While this URL works seamlessly for most users out of the box, networking complexities can sometimes prevent a successful connection. Understanding the underlying technology of this URL is essential for maintaining a reliable smart home infrastructure.

Understanding the Anatomy of the Home Assistant Local URL

To effectively manage a Home Assistant instance, it is vital to break down the default URL into its core components. Each segment plays a specific role in routing your browser to the correct hardware and service.

The Protocol: HTTP vs. HTTPS

By default, Home Assistant uses http://. This is an unencrypted protocol. In a local, trusted network environment, using HTTP is generally acceptable and simplifies access. However, if you have configured an SSL/TLS certificate (through Let's Encrypt or the DuckDNS add-on), your local URL must change to https://.

A common pitfall occurs when users enable SSL for external access but forget that this often forces the internal connection to also use HTTPS. If SSL is active, attempting to reach http://homeassistant.local:8123 will result in a connection error, as the server is expecting an encrypted handshake.

The Hostname: homeassistant.local

The segment homeassistant is the default hostname assigned during the Home Assistant Operating System (HAOS) installation. The .local suffix indicates that the address is managed via Multicast DNS (mDNS).

Unlike traditional DNS, which requires a central server (like a router or Google's 8.8.8.8) to translate names into IP addresses, mDNS allows devices on a local network to "announce" themselves. Your computer or smartphone broadcasts a query asking, "Who is homeassistant.local?" and the Home Assistant hardware responds directly with its IP address.

The Port: 8123

The number following the colon is the network port. Home Assistant defaults to port 8123. In networking, a single IP address can host multiple services; ports act like apartment numbers in a building. While web traffic typically uses port 80 (HTTP) or 443 (HTTPS), Home Assistant uses 8123 to avoid conflicts with other web services. You must include this port in the URL unless you have set up a reverse proxy (like NGINX) to redirect traffic.

Why the Local URL Might Fail to Resolve

It is a frequent occurrence in smart home forums: a user types the standard URL, only to be met with a "Site Can't Be Reached" error. Several technical factors contribute to this failure.

Lack of mDNS Support

mDNS, often branded as "Bonjour" by Apple or "Avahi" in Linux environments, is not universally supported.

Android Devices: Historically, many Android versions did not support mDNS natively in the mobile browser. While recent updates have improved this, many Android users still find that homeassistant.local fails while an IP address works perfectly.
Windows Configurations: Older versions of Windows or systems with certain security policies disabled may not have the LLMNR or mDNS features active.
Router Limitations: Some basic ISP-provided routers do not correctly handle multicast traffic, effectively blocking the "handshake" between your device and Home Assistant.

Network Isolation and Guest Wi-Fi

If your phone is connected to a "Guest" Wi-Fi network, it is likely isolated from the rest of your local devices for security reasons. Guest networks usually implement Client Isolation, which prevents one Wi-Fi client from communicating with another. To access the Home Assistant local URL, your controlling device must be on the main private network.

Multiple Subnets and VLANs

In more advanced "Prosumer" home networks (using equipment like Ubiquiti UniFi or TP-Link Omada), users often place IoT devices on a separate VLAN from their primary computers. Since mDNS is a broadcast protocol, it typically does not cross the boundary of a VLAN or Subnet. If your Home Assistant instance is on VLAN 20 and your laptop is on VLAN 10, homeassistant.local will not resolve unless you have configured an mDNS Reflector or Avahi Gateway on your router.

Accessing Home Assistant via IP Address

When the mDNS hostname fails, the most reliable alternative is using the direct IP address of the device. This bypasses the need for name resolution and talks directly to the hardware.

How to Find Your Home Assistant IP Address

There are three primary methods to identify the current IP address of your instance:

Router Admin Interface: Log into your router’s web dashboard (usually found at 192.168.1.1 or 192.168.0.1). Look for a section labeled "Connected Devices," "DHCP Client List," or "Network Map." Find the entry for homeassistant or the MAC address associated with your Raspberry Pi/NUC.
Home Assistant CLI: If you have a monitor and keyboard connected to your Home Assistant hardware, the command-line interface will display the current IP address on the welcome screen.
Network Scanning Apps: Applications like Fing (available for iOS and Android) can scan your entire network and list all active devices and their IP addresses.

Formatting the IP-Based URL

Once you have the IP (e.g., 192.168.1.100), the URL becomes: http://192.168.1.100:8123

The Critical Step: DHCP Reservation

Using an IP address comes with a major caveat: by default, routers assign "dynamic" IPs that can change whenever the router or the Home Assistant device restarts. If the IP changes from .100 to .105, your bookmarks and mobile app settings will break.

To prevent this, you should set up a DHCP Reservation (also called a Static IP) in your router settings. This tells the router to always assign the same IP address to the Home Assistant hardware based on its unique MAC address. This ensures that your local URL remains permanent and stable.

Configuring Internal and External URLs in Settings

Home Assistant allows you to explicitly define its access URLs within the software itself. This is crucial for certain integrations (like Mobile App notifications or Google Assistant) to function correctly.

Navigating to Network Settings

To configure these:

Go to Settings > System > Network.
Locate the Home Assistant URL section.
You will see fields for Internet and Local Network.

Local Network Configuration

In the Local Network field, enter your preferred local access method. If mDNS works reliably, enter http://homeassistant.local:8123. If you are using a static IP, enter the IP-based URL.

Pro Tip: If you use the Home Assistant Cloud (Nabu Casa), you don't need to manually configure the "Internet" URL, as it is handled automatically. However, keeping the "Local Network" URL accurate is vital for the Home Assistant Companion App to know when to switch from remote data to your home Wi-Fi for faster performance.

Troubleshooting the "No URL Available" Error

The "No URL Available" error typically appears when you are setting up an integration that requires OAuth2 authentication (such as Nest, Spotify, or Somfy).

Why This Error Occurs

OAuth2 involves a redirect flow. You go to the provider’s website, log in, and then the provider needs to send you back to your Home Assistant instance. For this to work, Home Assistant must tell the provider exactly where you are located. If Home Assistant hasn't been configured with a valid URL, it cannot provide this "Return To" address, and the authentication fails.

How to Resolve the Error

Enable Advanced Mode: Go to your User Profile in Home Assistant and toggle on "Advanced Mode." Without this, some network settings may be hidden.
Verify the URL: Ensure the URL in the Network settings matches exactly what you are seeing in your browser's address bar. Even a missing trailing slash or an accidental https instead of http can cause OAuth2 to fail.
Use the IP Address Temporarily: If homeassistant.local is causing the error during integration setup, try accessing the dashboard via the IP address and then re-initiating the integration. Often, the explicit IP provides a more "concrete" redirect path for the third-party provider.

Local Access with SSL: The Certificate Dilemma

Many users want to secure their Home Assistant instance with SSL (HTTPS). While this is great for security, it complicates local access.

The Problem with Local HTTPS

Browser security rules state that an SSL certificate is issued to a domain name (like myhouse.duckdns.org), not an IP address.

If you access https://192.168.1.100:8123, your browser will display a "Your connection is not private" warning because the certificate doesn't match the IP.
If you use https://homeassistant.local:8123, it might still show a warning because .local is not a globally recognized top-level domain.

The Solution: Hairpin NAT or Split Brain DNS

For the best experience when using SSL, you want to use your external domain name (e.g., https://myhouse.duckdns.org:8123) even when you are inside your home. This requires your router to support Hairpin NAT (Loopback). When you type your external URL while at home, the router realizes the destination is actually inside the network and routes the traffic locally.

If your router doesn't support Hairpin NAT, you can use a Local DNS server (like AdGuard Home or Pi-hole) to point your external domain name directly to the internal IP of Home Assistant. This is known as Split Brain DNS.

Setting Up the Home Assistant Companion App

The Home Assistant mobile app is designed to switch between local and remote URLs intelligently.

Internal URL Configuration

Inside the App settings (Settings > Companion App > Select your Server), you will find a field for Internal URL.

When to use it: This URL should be your http://homeassistant.local:8123 or your static IP address.
SSID Filtering: You can tell the app to only use the Internal URL when it detects you are connected to your specific home Wi-Fi SSID. This prevents the app from trying to use a local address when you are on cellular data or a friend's Wi-Fi.

In my experience, setting the Internal URL to a static IP is the most foolproof method for the mobile app. It avoids the 1-2 second delay sometimes caused by mDNS discovery, making the dashboard feel much snappier when you walk through the door.

Advanced Scenarios: Docker and Virtual Machines

The way you install Home Assistant significantly impacts how the local URL behaves.

Home Assistant Container (Docker)

If you are running Home Assistant in a Docker container (on a Synology NAS or a generic Linux server), the homeassistant.local address will not work by default. This is because the containerized version doesn't include the mDNS broadcast service (Avahi) that the full OS provides.

The Fix: You must access it via the host's IP address. Additionally, ensure you have mapped port 8123 in your Docker Compose file or run the container with --network=host to give it direct access to the network stack.

Virtual Machines (VirtualBox, Proxmox)

When running HAOS in a Virtual Machine, the "Network Adapter" setting is critical.

NAT Mode: This puts the VM behind a private virtual network. It will be unreachable via homeassistant.local from other devices.
Bridged Mode: This is the required setting. It allows the VM to appear as a physical device on your router, receiving its own IP address and allowing mDNS broadcasts to reach the rest of your home.

Troubleshooting FAQ

What should I do if "homeassistant.local:8123" is stuck on "Preparing Home Assistant"?

This usually occurs during the first boot. Home Assistant is downloading the latest updates. However, if it stays stuck for more than 20 minutes, it likely means the device has no internet access. Check your Ethernet cable and ensure your router is providing an internet connection to the device.

Can I change the ".local" hostname?

Yes. If you prefer http://smart-hub.local:8123, you can change this in Settings > System > Network > Hostname. Note that after changing this, you must use the new name for all future local connections.

Why does my browser say "Connection Refused"?

This error specifically means the browser reached the correct IP address, but there is no service listening on port 8123. This happens if:

Home Assistant is still booting up.
The Home Assistant Core service has crashed.
You have a firewall on your computer (like Windows Defender or an antivirus) blocking port 8123.

Is it possible to access Home Assistant locally without a port number?

Yes, but it requires a reverse proxy. By using the NGINX Proxy Manager add-on, you can map http://homeassistant.local (port 80) to the internal port 8123. This allows you to simply type the name into your browser.

Summary

Successfully accessing your Home Assistant local URL is the foundation of a functional smart home. While http://homeassistant.local:8123 is the standard, network environmental factors like mDNS support, VLAN configurations, and SSL settings often necessitate the use of a static IP address.

For the most stable experience, follow these three "Golden Rules" of Home Assistant networking:

Assign a DHCP Reservation in your router so your IP never changes.
Use the IP address if your devices or router struggle with mDNS (the .local address).
Correctly define your Internal URL in the Home Assistant network settings to ensure mobile apps and integrations function without errors.

By mastering these local access methods, you ensure that your home remains controllable even if your internet connection goes down, preserving the local-first philosophy that makes Home Assistant so powerful.