Troubleshooting Guide

Quick Diagnostics

Run the diagnostic command to check your LocalDNS setup:

localdns doctor

This checks daemon status, API connectivity, hosts file permissions, DNS resolution, port availability, domain registrations, dashboard accessibility, and Node.js version.

Common Issues

dns.local Not Loading (404 Errors)

Symptoms: Browser shows 404 errors, blank page, or "missing required error components" message.

Fixes:

1. Daemon not running

   localdns status  # Check if running
   localdns start   # Start daemon

2. dns.local not in hosts file

   grep "dns.local" /etc/hosts
   
   # Add if missing
   echo "127.0.0.1 dns.local" | sudo tee -a /etc/hosts
   
   # Or use doctor with --fix flag
   localdns doctor --fix

3. Dashboard domain not registered

   localdns list  # Check if dns.local is registered
   
   # Register dashboard
   localdns add dns.local --port 1111 --cmd "cd apps/dash && pnpm dev"

4. Dashboard not running

   localdns start dns.local

5. Port conflicts

   localdns ports  # Check port usage

Daemon Not Starting

Check logs:

cat ~/.localdns/daemon.log
cat ~/.localdns/daemon-error.log

Verify daemon binary exists:

ls -la services/daemon/dist/index.js

Rebuild if needed:

pnpm build

Port Conflicts

localdns ports              # Show port usage
lsof -i :80                 # Check port 80
lsof -i :1111               # Check port 1111

Change ports if needed:

export LOCALDNS_PORT=3002
export LOCALDNS_PROXY_PORT=8080
localdns start

Step-by-Step Troubleshooting

1. Check Daemon Status

localdns status

If daemon is stopped: localdns start

2. Verify DNS Resolution

ping dns.local
# Should resolve to 127.0.0.1

3. Check Domain Registration

localdns list

4. Start Dashboard Domain

localdns start dns.local

5. Verify Dashboard is Running

curl http://localhost:3001

6. Check Browser

• Clear browser cache
• Try incognito/private mode
• Check browser console for errors
• Verify URL is exactly http://dns.local (not https)

Advanced Diagnostics

# Check daemon logs
cat ~/.localdns/daemon.log

# Check API health
curl http://localhost:1111/api/status

# Check port usage
lsof -i :80
lsof -i :3001

Prevention

• Always run localdns doctor after installation
• Use localdns status regularly to check health
• Keep daemon running: localdns start