Troubleshooting

Practical checks for configuration drift, hostname issues, and runtime validation.

This page summarizes the most important troubleshooting patterns described or implied by the Mullgate usage material.

Start with the CLI

The primary diagnostic surfaces are:

mullgate proxy status
mullgate proxy doctor
mullgate proxy access
mullgate proxy validate --refresh

Common problems

Hostname does not select the expected route

Check for:

the hostname resolving to the wrong bind IP
two hostnames resolving to the same bind IP
a missing local hosts block
published DNS records that do not match the configured exposure state

What to do:

run mullgate proxy access
confirm the route-to-bind-IP mapping
if you are intentionally using hostname entrypoints, verify local hosts or DNS resolution
run mullgate proxy doctor

In loopback mode without a base domain, direct bind-IP entrypoints are the canonical local path. Missing host-file mappings only matter when you want hostname shortcuts on that same machine.

Remote clients cannot prove hostname-based routing

Check for:

the wrong host IP being shared with clients, especially 0.0.0.0 instead of the real Tailscale or LAN IP
missing or incorrect DNS records
exposure changes that have not been refreshed into runtime state

What to do:

use the real private-network host IP, such as the Mullgate host's Tailscale 100.x address
regenerate or review exposure output
publish matching DNS A records
run mullgate proxy validate --refresh or mullgate proxy start

Inline selector URLs do not select the expected route

Check for:

the client URL using scheme://selector@host:port and dropping the empty password
a selector that does not match any saved route or relay filter
public exposure with an empty password but no explicit unsafe override

What to do:

switch to the guaranteed scheme://selector:@host:port form
inspect selector examples with mullgate proxy access
if the listener is public and the password is empty, add --unsafe-public-empty-password or set a real password

For the supported selector families and the "must resolve to one target" rule, see Inline Selector Reference.

Saved configuration changed but runtime does not match

Likely cause:

exposure edits left runtime state marked unvalidated

What to do:

mullgate proxy validate --refresh
# or
mullgate proxy start

Installed command says the config version is unsupported

Likely cause:

the local machine still has a stale pre-v2 config/runtime bundle

What to do:

back up or remove the config file and runtime directory named in the error
rerun mullgate setup
rerun mullgate proxy start

Do not expect the current CLI to operate on the old runtime bundle in place.

macOS or Windows behaves differently from Linux

This is expected for the shipped multi-route Docker runtime because Docker Desktop host networking is not equivalent to Linux host networking.

What to do:

treat config and diagnostic surfaces as supported
use a Linux host or Linux VM for full runtime proof

`start` fails before launch

Look for:

missing Docker Compose support
invalid exposure edits
validation failures
missing HTTPS material when HTTPS is enabled

Use mullgate proxy status and mullgate proxy doctor to identify which layer failed.