Troubleshooting
Diagnose daemon, Caddy, certificate, and service startup issues.
devproxy list cannot reach the daemon
Run devproxy start to launch embedded Caddy in the background, then check devproxy status. The control API listens on 127.0.0.1:7654. If you changed its address, pass the matching --daemon option to run, register, list, status, and stop.
start cannot start the proxy
Check the log at devproxy/daemon.log under the user cache directory. For embedded mode, check that another proxy is not using port 443. On Linux, follow the port 443 setup. For external mode, start dedicated Caddy first and ensure its local admin API is reachable at the URL passed to --caddy-admin.
Browser reports an untrusted certificate
Caddy uses its local certificate authority for .localhost HTTPS. Follow the macOS trust steps, or trust that root certificate in your Linux system or browser. Embedded mode keeps the authority in the user config directory under devproxy/caddy; external Docker mode keeps it in a Compose volume.
run says the service did not start listening
The child has 60 seconds by default to open its allocated port on 127.0.0.1. Ensure it reads PORT or uses the substituted {port} argument. Increase --ready-timeout if startup takes longer. devproxy does not change application port settings beyond the environment variable and argument substitution.
register says the service is not listening
Start the service first and verify its port is reachable on 127.0.0.1. If it runs in Docker, publish its HTTP port to the host. Then run register --port with that host port.
Registration conflicts or a URL is missing
Run devproxy list to inspect active routes. A second registration for the same hostname and path prefix is rejected. Use another --worktree name or --route. Keep the run or register command running; its registration disappears on exit or expires after 20 seconds without heartbeats.