A .rex domain won't resolve

The symptom is the browser saying it cannot find the server — not a certificate warning, not a 502. Nothing answered the name.

Start here:

rex doctor

It checks the resolver file, whether rexenv’s DNS is answering, and whether something else has taken the TLD over — which is the cause more often than a broken rexenv.

The checks below are macOS’s, where .rex is a resolver file. On Linux it is a network link instead — its checks are at the end.

Check the resolver file exists

cat /etc/resolver/rex

It should name a nameserver on 127.0.0.1 and port 15353. If the file is missing, macOS is not asking rexenv about .rex at all — reinstall it from Settings, which re-runs the admin prompt from first run.

Check the DNS server is answering

dig @127.0.0.1 -p 15353 myshop.rex

An answer of 127.0.0.1 means DNS is fine and the problem is further along — check that the services are running with rex status.

No answer means the DNS agent is not running. It normally survives quitting the app and restarts itself, so this is worth reporting.

A toast reading “DNS stopped unexpectedly — restarted automatically” on 0.8.10 or earlier was often wrong about a resolver that had never stopped: the check was a single datagram with half a second to answer, and one miss restarted the agent. It now asks up to three times and restarts only after two silent polls in a row — so on a current build that toast means what it says.

Another tool has taken the TLD back

If you also have Valet, Herd, dnsmasq or a similar tool installed, more than one thing may be writing /etc/resolver files. The failure is confusing on its own: the file exists, it just points somewhere else.

This is common enough after a migration that rexenv now tells you rather than waiting to be asked. When a TLD rexenv was answering for gets reclaimed, the Sites screen shows a banner:

Your .test sites stopped resolving — Valet or Herd took .test’s resolver file back, so those sites won’t load until rexenv takes it over again. You can take it back from Import.

Import is where you take it back, with the same consent step as the original import — taking a TLD from another tool is exactly the kind of change that should not happen quietly, in either direction.

rex doctor reports the same thing from a terminal, which is the answer when the app is not in front of you.

A site on a second TLD, and its resolver file is gone

The default TLD’s health says nothing about a site — or an extra domain — on another TLD whose resolver file went away. nginx serves it, the edge routes it, the certificate covers it, and the browser still cannot find it. rex doctor and the DNS card in Settings name every TLD your sites answer on that this Mac cannot resolve, with the cause. The two causes need different fixes, and doctor prints the one that applies:

.test — no resolver file, so sites on it do not resolve on this machine, however well they are served fix: rex tld --repair test

rex tld --repair <tld> puts back the resolver file for a TLD your sites use, with the admin prompt. It refuses a file another tool owns — it will not take over a Valet or Herd resolver, which is the other cause:

.test — another tool owns the resolver file, so sites on it reach whatever it answers, not rexenv; rex tld --repair will not take a file it was never given (hand the TLD over in the app’s import, or use .rex)

rex tld --remove <tld> is the opposite verb: it removes a resolver file that is rexenv’s own and that no site still uses. Nothing removes one automatically — housekeeping must not prompt for a password.

It is worth understanding why this happens rather than treating it as a fight: both tools write the same file, and whichever ran most recently owns it. Starting Valet or Herd after rexenv will keep taking it back.

macOS caching

macOS caches negative DNS answers. If you fixed the cause and the name still will not resolve:

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

It resolves in the terminal but not in the browser

Chrome and Firefox can be configured to use DNS-over-HTTPS, which bypasses the system resolver and therefore bypasses /etc/resolver entirely. Turning off “Secure DNS” for the browser, or adding an exception, fixes it.

Safari uses the system resolver and is a useful control: if the site loads there but not in Chrome, this is why.

On Linux

.rex is routed through rexenv0, a dummy network link whose only routing domain is .rex. Ask systemd-resolved which link answered, not only what the answer was — on a VM or under WSL the upstream DNS is the host’s, and a host running rexenv answers *.rex with 127.0.0.1 by itself, so an unpinned lookup can succeed while rexenv’s own route does nothing.

resolvectl status rexenv0                   # 127.0.0.1:15353, ~rex, -DefaultRoute
resolvectl query -i rexenv0 yoursite.rex    # the answer through rexenv's link only
systemctl --user status rexenv-dns          # the resolver behind it

• Current Scopes: none on rexenv0 is a link systemd-resolved is not routing through. rexenv reads that as not installed, however many of its files are in place, and offers its setup step again — one password dialog re-applies the route. Two known causes: the first Linux release’s link had no address, and systemd-resolved gives no DNS scope to a link without one (it gets 192.0.2.53/32 now); and on 0.8.10 and earlier a re-apply deleted and re-created the link, which now and then lost its settings.
• “Your .rex route was set up by an older rexenv. It works — re-apply it once (one administrator prompt) so this version’s route is in place.” — a route an older rexenv wrote, still routing. It counts as installed: rex status prints the sentence under its DNS line, and Settings shows it with a Re-apply button. Re-apply, or rex tld --repair rex, rewrites it with one password dialog; the update itself never prompts for it. Until this notice existed, updating a Linux install from 0.8.10 opened onboarding’s Welcome screen over existing sites, with the resolver reported missing while .rex still resolved.
• No rexenv0 at all, or setup refused with “rexenv: systemd-resolved is not running on this machine, so a DNS route would change nothing.” — the route works only through systemd-resolved answering /etc/resolv.conf, which is Ubuntu’s default.
• The resolver is not running — systemctl --user restart rexenv-dns. It restarts by itself when it exits, and starts at every sign-in.