ESP32 .local Not Working on Android: mDNS Explained

Why an ESP32 .local hostname like gizmo-ticker.local fails on Android or a router, how to find the cause, and how to use the IP address with a reservation.

Published
Reading time
8 min
A maker scratches their head in front of a browser showing gizmo.local with a question mark, a sad phone, a Wi-Fi router and an mDNS label.

In short

A .local name needs mDNS: a multicast query on UDP 5353 that the phone, the router and the ESP32 must all allow. When it fails, use the board's IP address and reserve it on the router.

An ESP32 .local name fails when the asking device can't send an mDNS query, or never gets an answer to it. mDNS (multicast DNS) asks every device on the Wi-Fi network at once instead of a DNS server. Guest networks, VPNs, mobile data, some routers and Android resolvers without mDNS can all break it. The fallback is the board's IP address.

This guide uses the three OpenGizmo devices as the example, because each one advertises a .local name after it joins your Wi-Fi: gizmo-ticker.local, gizmo-reolink-switch.local and gizmo-camera.local. I read the firmware, the gizmo-common library and the AOSP, Apple, Espressif and RFC sources linked below, and I mark what I could not verify. Short on time? Jump to the checklist, then come back for the why.

What is mDNS and how does gizmo-ticker.local get resolved?

mDNS is defined in RFC 6762. It sends DNS-style messages over IP multicast to UDP port 5353, and treats any name ending in .local. as link-local, meaning it only has a meaning on the network where it was announced. Queries go to 224.0.0.251 (IPv4) or FF02::FB (IPv6). No server is involved: the device that owns the name answers.

A phone asks who has gizmo-ticker.local over multicast, the router passes it on and the ESP32 answers with its IP address; guest Wi-Fi, VPN and a blocked port 5353 break the chain

On the ESP32 side the gizmo-common library does three things, all in wifi_setup.cpp (version 2.5.1, pinned by the ticker and the Reolink switch; the camera pins 2.4.0, where I checked the same MDNS.begin and host check):

  • It starts mDNS only after the board has joined the Wi-Fi: startMdns() returns early unless WiFi.status() == WL_CONNECTED.
  • It calls MDNS.begin(hostname) and adds an http service on TCP port 80 with MDNS.addService("http", "tcp", 80).
  • It stops mDNS again when the connection drops or the setup hotspot opens, and restarts it after the next successful connection.

So after a router reboot, the name disappears until the board reconnects. The hostname is always the project name, set in each project's firmware, for example in the ticker's wifi.cpp: "gizmo-ticker". The Gizmo Ticker, the Gizmo Reolink Switch and the Gizmo Camera work the same way. For how the board got on your Wi-Fi in the first place, see ESP32 Captive Portal Not Working? Fix the Wi-Fi Popup.

Why does .local fail on some Android phones?

Support for .local names depends on the client operating system's resolver, not on the ESP32. The ESP32 answers the same way for everyone, so if a Mac resolves the name and a phone doesn't, look at the phone.

ClientResolves .local names?Source and date
AndroidYes through getaddrinfo(), since November 2021, but not on VPN or mobile dataAOSP DNS Resolver page
macOSYes, through BonjourApple documentation (2013 page, OS X era)
iOSNot stated on that Apple pageNot verified here
Linux with systemd-resolvedOnly if mDNS is enabled for the link: MulticastDNS= defaults to false in systemd.networksystemd.network man page
Windows 10 and 11Not verified hereNo primary source found

For Android, the AOSP DNS Resolver documentation says: "Starting from November 2021, Android resolver supports mDNS .local resolution". It implements the one-shot multicast query of RFC 6762, and apps get it by calling getaddrinfo() with a *.local name. The same page says VPN and mobile data connections are excluded. I confirmed that in the resolver code: res_cache.cpp has an is_mdns_supported_transport_types() function that returns false for cellular and VPN networks, and res_send.cpp sends the mDNS query for names flagged as mDNS.

What the page does not say is which Android versions have it. The code lives in packages/modules/DnsResolver, a module directory, so a phone's resolver version may not match its Android version. I found no primary list of versions, so I won't give one. Advice written before November 2021 may be out of date.

Four conditions for .local on Android: Wi-Fi rather than mobile data or VPN, a resolver with mDNS since November 2021, an app that uses getaddrinfo, and a router that passes multicast

Two more things can still bite on a recent phone:

  1. The app has to ask the system resolver. A browser or app that does its own DNS lookups, for example with a built-in secure DNS client, never reaches that code. This is my reading of the AOSP page: I did not test it on a phone.
  2. Apps can find the device without the name. The board registers an _http._tcp service, and Android's Network Service Discovery API browses DNS-SD services on the local network. It is for app developers, but an app using it can find the board by service type without resolving the .local name.

You can test a phone with a computer attached over adb: the AOSP page suggests adb shell ping6 HOSTNAME.local, so for the ticker that's adb shell ping6 gizmo-ticker.local. If that answers but the browser doesn't, the browser or its DNS settings are the likely cause.

How do you find the ESP32's IP address?

An IP address needs no name lookup, so it works whenever the phone can reach the board. The OpenGizmo devices accept requests under three names, per the gizmo-common README: the IP address, <hostname>, or <hostname>.local. Anything else gets a host_not_allowed error. This protects the board from DNS rebinding, but it also means a name your router invents, like gizmo-ticker.lan, won't open the web app: use the IP.

A phone fails to open gizmo-ticker.local while a router lists its clients with 192.168.1.50 highlighted, the address of the ESP32 board

Where to read it, in order of effort:

  1. The device itself. The Reolink switch's LCD shows its address on the NVR setup screen, per its README, and the dashboard's Device page lists it. The Device page and GET /api/device return ip and hostname once connected. The camera page of the Gizmo Camera web app shows the exact address and MCP command.
  2. The serial log. A debug build of the Reolink switch's firmware logs Connected, open http://gizmo-reolink-switch.local or http://<ip>. I did not check the other two for this line.
  3. Your router's client list. Look for a new device. Without a hostname set in firmware, the DHCP name is a default: Arduino-ESP32's docs say it's "assigned based on the chip type and MAC address". gizmo-common doesn't call WiFi.setHostname(), as far as I read, so expect that kind of name, not gizmo-ticker.

Then open http://192.168.1.50 with your board's address. If a page opens by IP but not by name, the board and the web app are fine, and the lookup is the culprit.

Which router and network settings block mDNS?

Several things on the network can block mDNS. Change one thing at a time, then test again.

CauseWhat you seeWhat to check
Client or AP isolationPhone and board both online, name fails, IP fails tooTurn off client isolation on the SSID; avoid guest networks
Different subnets or VLANsName fails; the IP may still work if the router routes between themPut the phone and board on the same subnet, or use the IP
Firewall on the asking computerName fails from one computer onlyAllow inbound UDP 5353 on that computer
VPN or mobile data on the phoneName fails on the phone onlyTurn the VPN off; use Wi-Fi

The espboards.dev troubleshooting page lists router blocking, a firewall on UDP 5353, and isolated hotspots or guest networks among the causes, plus calling MDNS.begin() only after Wi-Fi is up. It is a troubleshooting list, not a specification, so I use it as a checklist, and I verified the MDNS.begin() ordering in gizmo-common myself. The ESP32 itself needs no router setting.

How the test tells you what's wrong:

  • IP fails too: the network blocks traffic between clients (isolation) or the router doesn't route between the two networks. Fix that first: it is not an mDNS problem.
  • IP works, name fails on every device: the board's mDNS responder isn't running, or the devices are on different subnets. Check that the board is connected, and look for Failed to start mDNS in a debug build's log.
  • IP works, name works on a laptop but not on the phone: it's the phone, as in the section above.

How do you give the ESP32 a fixed address?

A DHCP reservation tells the router to always hand the same address to the same MAC address, so the board still uses DHCP and you don't touch the firmware. That is my pick for the OpenGizmo devices, because gizmo-common takes its address from the router, and the firmware doesn't call WiFi.config() for a static one.

  1. Find the board's MAC address in the router's client list, next to the current IP.
  2. Open the router's DHCP or LAN section and look for "address reservation", "static lease" or "bind IP to MAC". The names vary between routers.
  3. Pick an address in the LAN range, outside the DHCP pool if the router wants one, and save.
  4. Restart the board and check that the client list now shows the reserved address.

A static IP in firmware is the other option. Arduino-ESP32's WiFi API docs describe WiFi.config() for setting the local IP, gateway, subnet and DNS servers before begin. You then own the job of avoiding clashes with the router's pool. A reservation is safer for a household.

If you ever run two of the same OpenGizmo device on one network, they will both try to claim the same .local name. RFC 6762 section 9 says the loser must stop using the name and pick a new one. The Espressif mDNS docs I read don't describe how the ESP32 component handles it, and I haven't tested it, so reach each by its own IP.

How do you set the hostname in Arduino code?

Two different names exist, and people mix them up. The mDNS name is what MDNS.begin() sets. The DHCP name, set with WiFi.setHostname(), is how the board shows up in the router's list. The Arduino-ESP32 docs say setHostname() "must be called BEFORE Wi-Fi is started", while mDNS is started after the connection. This is a minimal sketch, built from those docs and the gizmo-common logic, not compiled for this post:

hostname.ino
hostname.ino
#include <WiFi.h>
#include <ESPmDNS.h>

void setup() {
    WiFi.setHostname("gizmo-ticker"); // DHCP name in the router's list, before WiFi.begin()
    WiFi.begin("my-ssid", "my-password");
    while (WiFi.status() != WL_CONNECTED) {
        delay(250);
    }

    // Only after the connection is up
    if (MDNS.begin("gizmo-ticker")) {
        MDNS.addService("http", "tcp", 80);
    }
}

void loop() {}
Ln 17, Col 1UTF-8cpp

Reach it at http://gizmo-ticker.local. ESPmDNS doesn't validate the name, so keep it to lowercase letters, digits and hyphens, as the OpenGizmo hostnames do. For a finished example with reconnects, read startMdns() in gizmo-common, or the Reolink Switch build that uses it.

Checklist: the .local name doesn't open

  1. Are the phone and the board on the same Wi-Fi network, and is the phone on Wi-Fi rather than mobile data, with the VPN off?
  2. Does the board's IP address open the web app? If not, fix client isolation or the subnet first.
  3. Does the name work from a laptop on the same network? If yes, the board is fine and the phone's resolver or app is the cause.
  4. On a phone with adb: does adb shell ping6 gizmo-ticker.local answer?
  5. Did the board reconnect after a router reboot? mDNS only runs while it's connected.
  6. Is another device claiming the same name?
  7. Still stuck? Use the IP, and reserve it on the router so the address stops moving.

For the camera, the same rule applies to scripts: the snapshot URL guide and the MCP server guide both work with the IP in place of gizmo-camera.local.

What was verified, and the limits

I read the mDNS start and stop logic and the host check in gizmo-common 2.5.1, the hostnames in the three firmwares, and Android's resolver code and documentation, as of November 2026. I did not run any of it on a phone, router or board for this post: the adb command, the router steps and the sketch are derived from the sources, not measured. Windows support is not verified, the Android versions with mDNS are not listed by any source I found, and routers vary a lot in what they call their settings.

If the name still fails after the checklist, the IP and a reservation are not a defeat: they are what a household network wants. For how the board got its Wi-Fi in the first place, compare the options in ESP32 Wi-Fi Provisioning: Captive Portal, BLE, Improv, and for the whole system, see what OpenGizmo is.

Frequently asked questions

Find quick answers to the most common questions about this topic.

A .local name only resolves if the phone sends an mDNS multicast query and the router passes it on. Android's resolver supports this since November 2021 per AOSP, but not on VPN or mobile data connections, and a router with client isolation blocks it. The reliable fix is to open the ESP32's IP address.

Published

Ready to build your own gizmo?

Pick an open-source ESP32 project and follow its step-by-step guide, from the parts list and wiring to the firmware and the first boot.

Read also

Explore categories