Troubleshooting

When something isn't working, start with the built-in diagnostics:

bash

lerd doctor   # full check: podman, systemd, DNS, ports, images, config
lerd status   # quick health snapshot of all running services

lerd doctor reports OK/FAIL/WARN for each check with a hint for every failure.

Filing a bug report

If you need help on the issue tracker, run:

bash

lerd bug-report

This writes a single plain-text file (default: ./lerd-bug-report-<timestamp>.txt) containing the full lerd doctor output, your config.yaml and sites.yaml, the state of every lerd-* systemd unit, recent journal and container logs for lerd's own infra units, listening sockets on the lerd ports, and a curated set of environment variables.

What gets filtered before it lands on disk:

Site .env files are excluded outright.
Home paths render as $HOME and the username as $USER.
Site names, domains and parked-directory paths are replaced with site-1/site1.<tld>/$PARK_1 placeholders. Pass --show-real-names to keep the raw values for local debugging.
Logs are kept only for lerd's own infra (lerd-nginx, lerd-ui, lerd-dns, lerd-watcher, lerd-tray, etc.). Preset services (mysql, redis, meilisearch, gotenberg, …), FPM containers and per-site workers still appear in the unit-state and container tables but their logs are dropped — they were producing repetitive request-shaped noise that didn't help triage.
Custom services and per-site custom / FrankenPHP containers are omitted entirely so the report doesn't expose user app identifiers.
Nginx structured error lines have their request: / upstream: / referrer: URI fields redacted, and HTTP access lines are dropped.

Skim the file before posting (it's plain text — open it in any editor) and attach it to your GitHub issue.

Override the destination with --output, change how many log lines per service to include with --log-lines, or keep raw site names with --show-real-names:

bash

lerd bug-report --output /tmp/report.txt --log-lines 500
lerd bug-report --show-real-names

.test domains not resolving

First, confirm DNS is actually meant to be managed by lerd. If lerd dns:check reports DNS managed externally, you opted out of dnsmasq during install and your sites should be on *.localhost rather than *.test. See DNS for switching modes.

Otherwise, the fastest way to find the broken rung is lerd doctor. The DNS section walks the chain top to bottom and surfaces exactly where it breaks, with a hint per failure:

[DNS]
  DNS TLD (.test)                     OK
    lerd-dns container                running
    dnsmasq config                    address=/.test/127.0.0.1, port=5300
    port 5300 listening               127.0.0.1:5300
    dig @127.0.0.1 -p 5300            127.0.0.1
    resolver hookup                   NetworkManager dispatcher: /etc/NetworkManager/dispatcher.d/99-lerd-dns
    interface routes .test to 5300    enp14s0
    system DNS lookup                 127.0.0.1

The chain in order:

Rung	What it checks	If it fails
`lerd-dns container`	The dnsmasq container is running.	`lerd start` (or `podman logs lerd-dns` to see why it crashed).
`dnsmasq config`	`~/.local/share/lerd/dnsmasq/lerd.conf` exists with `port=5300` and `address=/.<tld>/`.	`lerd start` regenerates the config from your registered TLD.
`port 5300 listening`	TCP/UDP 5300 is reachable on 127.0.0.1.	Another process owns the port. Find it with `ss -tlnp sport = :5300` on Linux, or `lsof -nP -iTCP:5300 -sTCP:LISTEN` on macOS.
`dig @127.0.0.1 -p 5300`	A direct query at port 5300 returns 127.0.0.1 for `lerd-probe.<tld>`.	dnsmasq is up but its config drifted. `systemctl --user restart lerd-dns`.
`resolver hookup`	The NetworkManager dispatcher script or systemd-resolved drop-in is installed.	Rerun `lerd install`.
`interface routes .test to 5300`	`resolvectl status` shows `127.0.0.1:5300` and `~<tld>` on the active interface.	`sudo systemctl restart NetworkManager`, or set the routing manually with `sudo resolvectl domain <iface> ~test ~.`.
`system DNS lookup`	`host lerd-probe.test` (the system resolver) returns 127.0.0.1.	The drop-in is installed but resolved isn't honouring it. Check whether cloud-init or another tool wrote a higher-priority resolver config. Common on EC2 / cloud images. With a VPN connected this rung is reported as a warning rather than a failure, see the VPN section below.

You can also call this programmatically over MCP via the diag tool's dns_diagnose action, useful for AI-driven troubleshooting:

bash

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"diag","arguments":{"action":"dns_diagnose"}}}' | lerd mcp

The response includes a steps array with a status (ok / fail / warn / skip) and hint per rung, plus a first_failure index so an LLM can jump straight to the broken layer.

DNS shows "Degraded" while connected to a VPN

VPN clients such as Cisco AnyConnect, ProtonVPN, Mullvad, and WireGuard take over the system resolver when they connect, rewriting systemd-resolved so .test no longer routes to lerd-dns through the normal path. lerd-dns itself keeps running and answering, so the dashboard shows a yellow Degraded pill rather than a red Failed one, and lerd doctor reports the system DNS lookup rung as a warning instead of a failure. Sites still resolve, because lerd-dns answers directly on 127.0.0.1:5300.

The watcher subscribes to kernel rtnetlink link and address events on Linux, so it reacts to a VPN connect or disconnect within a second of the interface coming up or going down (a poll every 30 seconds covers the rare case of a missed kernel event). When the host resolver environment changes, it re-points the lerd network's aardvark-dns at the current host resolvers and reloads the network so containers pick them up with a fresh cache. This is what previously required a manual lerd restart after connecting the VPN before PHP could reach VPN-internal API endpoints. The re-sync briefly (about a second) interrupts DNS for lerd containers while aardvark-dns restarts.

If you want the system resolver path itself restored while the VPN is up, so the pill goes back to green, move resolve after dns in the hosts: line of /etc/nsswitch.conf:

text

hosts: mymachines mdns_minimal [NOTFOUND=return] files myhostname dns resolve

This makes glibc consult the plain dns module before systemd-resolved's nss-resolve, which the VPN client no longer shadows.

Nginx not serving a site

Check that nginx and the PHP-FPM container are running, then inspect the generated vhost:

bash

lerd status                         # check nginx and FPM are running
podman logs lerd-nginx              # nginx error log
cat ~/.local/share/lerd/nginx/conf.d/my-app.test.conf   # check generated vhost

My custom nginx directive disappeared after an update

Don't edit ~/.local/share/lerd/nginx/conf.d/*.conf directly. Lerd regenerates those files on lerd link, lerd secure, lerd site rebuild, and every lerd install (which lerd update re-execs). Drop your snippet in ~/.local/share/lerd/nginx/custom.d/{domain}.conf instead — the generated vhost ends with an include for that file, and lerd never writes into custom.d/. See Nginx Overrides for examples.

PHP-FPM container not running

Check the systemd unit status and logs:

bash

systemctl --user status lerd-php84-fpm
systemctl --user start lerd-php84-fpm
podman logs lerd-php84-fpm

If the image is missing (e.g. after podman rmi):

bash

lerd php:rebuild

podman exec fails with "chdir: No such file or directory"

This happens when your project is outside your home directory (e.g. /var/www/, /opt/projects/). The PHP-FPM and nginx containers only mount $HOME by default.

Lerd handles this automatically: when you lerd link, lerd park, or run any exec command (lerd php, composer, laravel new) from an outside path, lerd adds the volume mount and restarts the affected containers.

If you see this error on an older lerd version, update to the latest and re-link the site:

bash

lerd update
lerd unlink && lerd link

To verify the mounts are in place:

bash

grep Volume ~/.config/containers/systemd/lerd-nginx.container
grep Volume ~/.config/containers/systemd/lerd-php*-fpm.container

You should see your project path listed alongside the %h:%h mount.

Permission denied on port 80/443

Rootless Podman cannot bind to ports below 1024 by default. Allow it:

bash

sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80
# Make permanent:
echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee /etc/sysctl.d/99-lerd.conf

lerd install sets this automatically, but it may need to be re-applied after a kernel update.

Watcher service not running

The watcher monitors parked directories, site config files, git worktrees, and DNS health. If sites aren't being auto-registered or queue workers aren't restarting on .env changes:

bash

lerd status                            # shows watcher running/stopped
systemctl --user start lerd-watcher   # start it from the terminal
# or use the Start button in the UI under System > Watcher

To see what the watcher is doing:

bash

journalctl --user -u lerd-watcher -f
# or open the live log stream in the UI under System > Watcher

For verbose output (DEBUG level), set LERD_DEBUG=1 in the service environment:

bash

systemctl --user edit lerd-watcher
# Add:
# [Service]
# Environment=LERD_DEBUG=1
systemctl --user restart lerd-watcher

HTTPS certificate warning in browser

The mkcert CA must be installed in your browser's trust store. Ensure certutil / nss-tools is installed, then re-run lerd install:

Arch: sudo pacman -S nss
Debian/Ubuntu: sudo apt install libnss3-tools
Fedora: sudo dnf install nss-tools

After installing the package, run lerd install again to register the CA.

PHP image build is slow on first run

lerd normally pulls a pre-built base image from ghcr.io and finishes in ~30 seconds. If you see it fall back to a local build instead, the most common cause is being logged into ghcr.io with expired or unrelated credentials; the registry rejects the authenticated request even though the image is public.

lerd handles this automatically since v1.3.4 by always pulling anonymously. If you are on an older version, running podman logout ghcr.io before the build will fix it.

Nginx fails to start (missing certificates)

lerd start automatically detects SSL vhosts that reference missing certificate files and repairs them before starting nginx:

Registered sites: the site is switched back to HTTP and the vhost is regenerated. The registry is updated (Secured = false).
Orphan SSL vhosts: configs left behind by unlinked sites with missing certs are removed.

Repaired items are printed as warnings during startup:

  WARN: missing TLS certificate for myapp.test, switched to HTTP

To re-enable HTTPS after the automatic repair, run lerd secure <name>.

If nginx still fails to start, check the logs:

bash

journalctl --user -u lerd-nginx -n 30 --no-pager

Port conflicts on lerd start

lerd start checks for port conflicts before starting containers. If another process is already using a required port, you'll see a warning:

Port conflicts detected:
  WARN: port 80 (nginx HTTP) already in use, may fail to start (check: ss -tlnp sport = :80)

Common culprits are Apache, another nginx instance, or a previously running lerd that wasn't stopped cleanly. Find and stop the conflicting process:

bash

# Linux
ss -tlnp sport = :80

# macOS
lsof -nP -iTCP:80 -sTCP:LISTEN

The exact command lerd suggests in lerd doctor and lerd start output is already platform-correct, so you can copy it from there.

lerd doctor also checks for port conflicts as part of its full diagnostic, and adds a dedicated [Stopped service ports] section that flags installed services whose host port is already bound by another process. The same warning is shown next to the inactive status pill in the web UI, so you can spot the conflict without running anything: most often this is a system-installed service (Postgres, MySQL, Redis) listening on the default port. Stop the conflicting process and the warning clears on the next snapshot refresh.

Workers missing after reinstall

If you ran lerd uninstall and then reinstalled, worker units and service quadlets are deleted during uninstall. Running lerd start after reinstalling automatically restores them from the workers list saved in each site's .lerd.yaml. If .lerd.yaml does not exist or was not committed, you will need to start workers again manually (lerd queue:start, etc.).

To check what was restored:

bash

lerd status   # shows all active workers and services

Workers failing or crash-looping

Check lerd status, the Workers section lists all active, restarting, or failed workers. In the web UI, failing workers show a pulsing red toggle and a ! on their log tab.

To inspect the error:

bash

journalctl --user -u lerd-queue-my-app -f    # or lerd-horizon-my-app, lerd-schedule-my-app

Common causes:

Missing Redis when QUEUE_CONNECTION=redis, start it with lerd service start redis
Missing dependencies after a fresh clone, run lerd setup to install them
Bad .env values, run lerd env to reset service connection settings

When you unlink a site, crash-looping workers are automatically detected and stopped.

Error: NetworkUpdate is not supported for backend CNI: invalid argument

Your system is likely configured to use the older CNI backend, which lacks support for the requested network operation. Edit or create the Podman configuration file at /etc/containers/containers.conf and add or modify the network_backend setting to netavark:

toml

[network]
network_backend = "netavark"

To ensure a clean switch and recreate the networks with the new backend, reset the Podman storage. Warning: this will wipe all existing containers, pods, and networks:

bash

podman system reset

Error: unknown flag: --dns (during lerd install)

Symptom: lerd install aborts at the podman network create step with Error: unknown flag: --dns.

Cause: your podman is older than 4.5. The --dns flag on podman network create was added in podman 4.5 (April 2023), and lerd needs it to write upstream DNS servers into netavark's per-network JSON atomically (otherwise the post-create network update --dns-add path crashes on Ubuntu 24.04's netavark <1.11). Distributions that ship podman older than 4.5: Ubuntu 22.04 / Zorin 17 (3.4.4), Debian 12 (4.3.1), Debian 11 (3.0.1).

Fix: upgrade podman to 4.5 or newer. On Ubuntu 22.04 and Zorin 17 the main archive doesn't ship a new enough podman, but the Kubic libcontainers OBS repo does (it's the path podman's own docs recommend). On Debian 12 enable bookworm-backports and run sudo apt install -t bookworm-backports podman. See the requirements page for the full distro/version table.

Error: unable to parse ip fe80::...%18 specified in AddDNSServer: invalid argument

Your host's DNS configuration includes a zoned link-local IPv6 nameserver, typically advertised by your router via SLAAC + RDNSS. The zone identifier (%18 is a kernel interface index) is meaningless inside a container's network namespace, and netavark refuses to accept it.

Lerd 1.18+ filters these addresses automatically before handing them to podman. If you're still on 1.17 or older, upgrade with lerd update and rerun lerd install. The filter is conservative: only zoned link-local (fe80::...%iface) addresses are dropped; globally routable IPv6 nameservers (e.g. 2606:4700:4700::1111) are preserved.

When filtering empties the entire DNS list, lerd falls back to pasta's standard forwarder (169.254.1.1), which bridges into the host's resolver and preserves .test routing.

Containers can resolve .test over IPv4 but not over IPv6

Lerd 1.18+ creates the lerd podman network as dual-stack (v4 + v6) and writes both A and AAAA records for .test domains. If you upgraded from an older version, the existing v4-only lerd network is migrated automatically the next time you run lerd install: attached containers stop, the network is recreated with the fd00:1e7d::/64 ULA prefix, the previous DNS server list is restored, and the containers restart. Quick check:

bash

podman network inspect lerd --format '{{.Subnets}}'
# expect both an IPv4 subnet and one starting with fd00:1e7d::

If the v6 subnet is missing, run lerd install once to migrate. To verify resolution from inside a container:

bash

podman run --rm --network lerd alpine sh -c 'nslookup laravel.test; nslookup -type=AAAA laravel.test'

Services fail to start with "aardvark-dns failed to bind [fd00:1e7d::1]:53"

Symptom: after lerd install, a subset of service containers (commonly lerd-nginx, lerd-postgres, lerd-meilisearch) fail to start. Journal shows:

Error: netavark: error while applying dns entries: IO error: aardvark-dns failed to start
Error starting server failed to bind udp listener on [fd00:1e7d::1]:53:
IO error: Cannot assign requested address (os error 99)

Cause: the host advertises IPv6 in the kernel but has no routable v6 address on any interface — only ::1 and fe80:: — so netavark can't hold the ULA gateway on the rootless bridge, and aardvark-dns bind fails with EADDRNOTAVAIL. Typical in headless QEMU/KVM VMs and networks without v6 DHCP.

Lerd 1.18+ detects this on every lerd install by reading /proc/net/if_inet6 (any non-loopback, non-link-local v6 address counts as usable) and falls back to a v4-only lerd network. An existing dual-stack network on a v6-less host is recreated as v4-only automatically. Force it:

bash

lerd install
# look for: "Recreated lerd network as v4-only (host has no usable IPv6)."

If the host later gains v6 connectivity, the next lerd install will recreate the network as dual-stack again.

If you'd rather skip the dual-stack code path entirely, even on a v6-capable host, opt out:

bash

lerd install --no-ipv6
# or persistently via shell rc:
export LERD_DISABLE_IPV6=1

Either path writes ~/.local/share/lerd/ipv6-probe-failed-lerd, which EnsureNetwork honors on every code path (initial create, migration, recreate). To re-enable dual-stack, delete that marker file and re-run lerd install.

Every DNS lookup inside a lerd container stalls ~5 seconds

Symptom: pages that hit the database or any container-to-container hostname feel slow, and time dig <anything> @<container> takes roughly five seconds before returning an answer. The network looks fine in podman network inspect lerd (both IPv4 and IPv6 subnets present), but aardvark-dns's on-disk config has the v6 gateway absent from its listen-ips line.

Cause: podman network rm doesn't clean up $XDG_RUNTIME_DIR/containers/networks/aardvark-dns/<name> between rm and recreate, so a network that was originally v4-only can leave aardvark with a v4-only listen header even after the network is recreated dual-stack. The container's /etc/resolv.conf still lists the v6 gateway as the primary nameserver, queries to it time out (~5s), then glibc falls back to the v4 gateway.

Lerd 1.18+ detects this drift on lerd install (aardvark listen line is v4-only despite the network being dual-stack) and self-heals by recreating the network with the stale aardvark state wiped. If you're on an earlier 1.18 build or the heal didn't fire, force it:

bash

lerd install

Manual verification:

bash

cat "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/containers/networks/aardvark-dns/lerd" | head -1
# expect both gateways, e.g.: fd00:1e7d::1,10.89.7.1 169.254.1.1
# if only 10.89.7.1 is present, the drift fix didn't run — re-run lerd install

Podman Machine overlay-storage error (macOS)

Symptom: on macOS, lerd start fails and every container start reports a graph-driver / overlay error:

exit status 125: Error: getting graph driver info "<id>":
readlink /var/lib/containers/storage/overlay: invalid argument

Cause: the macOS host was shut down ungracefully (forced power-off, battery death, kernel panic) while the Podman Machine VM was still running. The VM's container storage is left with a stale overlay mount and corrupt container layers, so no container can start until the storage is remounted and the stale containers are rebuilt.

lerd start detects this and self-heals automatically on the first run: it restarts the Podman Machine to remount the storage, force-removes the stale lerd-* containers so they rebuild on fresh storage, and retries the start pass once. Your data is safe throughout: lerd bind-mounts every database and site directory to the host, not into the VM.

If the automatic recovery isn't enough (it prints guidance pointing here), recreate the VM:

bash

lerd machine reset

This stops the VM, removes it, and re-initialises it. Databases and site data are preserved (they live on the host); container images are rebuilt automatically on the next lerd start. See Start, Stop & Autostart → lerd machine reset.

Troubleshooting ​

Filing a bug report ​

Troubleshooting

Filing a bug report