Running mdocker doctor

Whenever something isn’t working, run this first:

mdocker doctor

doctor is a read-only health check of your entire toolchain and MultiDocker state. It changes nothing — it just tells you what’s wrong and, where it can, how to fix it.

What it checks

scripts/doctor.sh runs through the whole stack:

Category	Checks
Container runtime	docker and docker compose v2 present and working
Toolchain	yq (mikefarah v4), jq, mkcert, tmux available
TLS	the wildcard certificate exists and covers every configured base domain
DNS	the /etc/resolver/<base-domain> file exists and actually resolves
Network	the multi-docker-edge docker network exists
Edge stack	the edge containers are running
Ports	80, 443 and 53 are available (or held by the edge stack, not a foreign process)

DNS is verified, not just assumed

The DNS check doesn’t only look for the resolver file — it performs a real lookup against a probe hostname (dscacheutil -q host -a name <probe>.<base-domain>). That catches the common “resolver file present but not active” case, where a fresh Mac hasn’t reloaded the resolver config yet. See DNS & TLS.

Reading the output

Each check reports its status and, on failure, a short message and a suggested fix. Work top-down — earlier checks are foundational (no container runtime means nothing else can pass), so fixing the first red item often clears several below it.

Typical fixes surfaced by doctor:

• Missing tool → brew install <tool>.
• Missing cert → mdocker setup-tls.
• Missing/inactive resolver → mdocker setup-dns (or bash scripts/setup-dns.sh).
• Missing network → mdocker setup-network.
• Edge down → mdocker edge up.
• Port held by a foreign process → doctor names the offending process so you can stop it.

Machine-readable output

For scripting or the app, add --json:

mdocker doctor --json

Each row carries a category, name, status, message and fix. The macOS app consumes exactly this: the Doctor view groups the checks by category and can attempt auto-fixes for the ones it knows how to repair.

In the app

Click the Doctor button in the toolbar. It runs the same check and shows the grouped results, with copy-the-fix and run-auto-fix buttons. It’s the graphical equivalent of the CLI command — same data, same conclusions.

When doctor is green but it still fails

If every check passes and a specific project still won’t load, the problem is likely project-level rather than infrastructure-level. Move on to Common Issues and Reading Edge & Traefik Logs.