Troubleshooting & FAQ

Start with mullion doctor. The rest of this page covers the questions people ask most.

Start with doctor

$ mullion doctor

It checks:

• the binary
• every port and who owns it
• Caddy's identity and config
• PHP, Node and the databases
• the wake agent
• every site

Each problem is marked in red, with its fix. You can also run it from Settings → Diagnostics. Please paste the output when you open an issue.

Why does linking a site ask for my password?

New domains are written to the hosts file (/etc/hosts or C:\Windows\System32\drivers\etc\hosts) inside a marked block that Mullion manages. Writing there needs administrator rights:

• From a terminal you get a sudo prompt.
• From the panel or the background agent you get the system password dialog on macOS, or UAC on Windows.

Wildcard subdomains use wildcard DNS instead of the hosts file.

The browser says the certificate isn't trusted

Run mullion ssl trust, or click Trust again on the Ports & SSL page. Firefox, phones and VMs have their own trust stores: run mullion ssl export ~/mullion-ca.crt and import the file there.

php -v or node -v shows another version

Another install comes earlier on your PATH: Laragon or XAMPP on Windows, nvm or Homebrew on macOS. mullion use and mullion node use detect this and offer to disable the offending entry. Then open a new terminal. mullion node which explains exactly which Node resolves in the current folder and why.

A frontend link shows an error page

The page shows the real reason and the end of the dev server's log. Fix it and refresh; mullion doctor shows the same details. Common causes:

• A dependency failed to install.
• The project needs a different Node version: pin it with mullion node isolate or add an .nvmrc.
• The dev script doesn't start a server.

Vite (or another dev server) and ports

Each frontend site has a stable dev port, and Mullion proxies the domain to whatever port the server actually opened. If the assigned port is taken, pick another with mullion port dev <site> <port>, the project's Domains tab, or the Ports & SSL page. Vite's "Blocked request. This host is not allowed" is handled for you: the proxy sends the dev server a localhost Host header, and the original name arrives in X-Forwarded-Host.

git push fails from the panel

The panel can't type a password or an SSH key passphrase. Sign in once in a terminal and your credential helper or SSH agent remembers it:

$ ssh-add --apple-use-keychain ~/.ssh/id_ed25519   # macOS: store the passphrase in the keychain

On Windows, start the OpenSSH Authentication Agent service and run ssh-add. For HTTPS remotes, run the Git command once in the built-in terminal.

Wildcard subdomains don't resolve

* aliases need mullion dns on. mullion dns status shows whether the resolver hookup and the DNS server are in place. On Windows, port 53 must be free; Internet Connection Sharing and local DNS proxies can hold it.

A port is already in use

mullion ports (or the Ports & SSL page) shows who holds it. When an old stack or a resurrected Homebrew service holds 80, 443 or 3306, mullion start and setup offer to stop it. To keep both, move Mullion's database with mullion port set.

A queue worker keeps restarting

After 5 crashes within 2 minutes a worker is marked crash-looping and left stopped. Open its Logs (or run mullion worker logs <site> <id>), fix the cause, and start it again.

Antivirus flags mullion.exe

Unsigned Go binaries are sometimes flagged. The build embeds an icon, version information and a manifest, and it's deliberately not stripped, all of which reduce false positives. If it happens, report the false positive to your antivirus vendor. Scoop and the Releases page publish the same binary.

Where are the logs?

In ~/.mullion/logs/ (C:\Mullion\logs\ on Windows), including one log per dev server and one per worker (worker-<site>-<id>.log).