Common Issues

Most problems fall into a handful of buckets. Find your symptom below; if it isn’t here, start with mdocker doctor, which diagnoses all of these automatically.

Symptom → cause → fix

Symptom	Cause	Fix
`bind: address already in use` on 80/443	A foreign process (Apache, nginx, another proxy) holds the port	`mdocker doctor` names the offending process — stop it, or `mdocker edge down`
Browser shows `NET::ERR_CERT_AUTHORITY_INVALID`	The mkcert CA isn’t installed in your trust store	`mkcert -install`, then restart the browser
Hostname won’t load (“connection refused” / not resolved)	The DNS resolver is missing or inactive	Ensure `/etc/resolver/<base-domain>` contains `nameserver 127.0.0.1`; otherwise run `mdocker setup-dns` (or `bash scripts/setup-dns.sh`)
Container fails to start with `network multi-docker-edge not found`	The edge docker network doesn’t exist	`mdocker setup-network` (or `bash scripts/setup-network.sh`)
`mdocker up` aborts with exit code 2	The port pre-flight found a busy host port and no free replacement	Free the port, or run `mdocker up <name> --auto-remap-ports` (or `--no-port-check`)
Traefik doesn’t answer / routes to the wrong place	Edge stack is down, or the project’s labels aren’t set	`mdocker edge status`, then `mdocker edge logs -f`; re-render the project with `mdocker rerender <name>`

A few of these in detail

`bind: address already in use`

MultiDocker binds ports 80, 443 and 53 on the loopback address for its edge stack. If a system Apache/nginx, another dev proxy, or a lingering container already holds one, the edge stack can’t start. mdocker doctor identifies the process; stop it and try again.

Certificate authority invalid

The wildcard cert is issued by a local mkcert CA. If your browser doesn’t trust it, the CA isn’t installed in the system trust store. Run mkcert -install and fully restart the browser (not just the tab). This is also what mdocker setup-tls ensures. See DNS & TLS.

Hostname won’t resolve

A present-but-inactive resolver file is the classic trap: macOS may not have reloaded /etc/resolver/<base-domain> yet. mdocker doctor verifies actual resolution, so trust it over “the file is there”. Re-running mdocker setup-dns flushes the cache and reloads mDNSResponder.

Exit code 2 on `up`

This is the port-conflict pre-flight refusing to start because a host port a service wants is taken and it couldn’t find a free replacement to apply automatically. Either free the port or let MultiDocker remap it with --auto-remap-ports.

Traefik routing wrong or silent

If a project’s page 404s through Traefik or hits the wrong container, either the edge stack isn’t running, or the project’s generated labels are stale. Check mdocker edge status, stream mdocker edge logs -f while you reload, and if the labels look wrong, regenerate the override with mdocker rerender <name>. See Reading Edge & Traefik Logs.

MultiDocker · Coding9 GmbH