Troubleshooting

This guide helps you diagnose and resolve common issues with NextDNS Blocker.

Quick Diagnostics

Run these commands to gather information:

# Check overall status
nextdns-blocker status

# Validate configuration
nextdns-blocker config validate

# Check watchdog
nextdns-blocker watchdog status

# Preview sync behavior
nextdns-blocker config push --dry-run --verbose

Common Issues

Domain Not Blocking

Symptoms: Domain accessible when it should be blocked

Diagnosis:

# Check domain status
nextdns-blocker status | grep domain.com

# Check schedule evaluation
nextdns-blocker config push --dry-run -v | grep -A10 domain.com

Common causes and fixes:

1. Within scheduled hours

   • Check current time vs schedule
   • Verify timezone is correct

2. Domain in allowlist

   nextdns-blocker config show | grep -A2 allowlist
   nextdns-blocker disallow domain.com

3. DNS cache

   # macOS
   sudo dscacheutil -flushcache
   
   # Linux
   sudo systemctl restart systemd-resolved
   
   # Windows
   ipconfig /flushdns

4. Browser cache

   • Clear browser cache
   • Try incognito/private window

Domain Not Unblocking

Symptoms: Domain blocked when it should be accessible

Diagnosis:

nextdns-blocker config push --dry-run -v | grep -A10 domain.com

Common causes:

1. Outside scheduled hours

   • Verify current time
   • Check timezone setting

2. Panic mode active

   nextdns-blocker panic status

   Wait for expiration or (emergency only) delete .panic file.

3. Watchdog not running

   nextdns-blocker watchdog status
   nextdns-blocker watchdog install

4. Sync not running

   nextdns-blocker config push --verbose

Watchdog Not Working

Symptoms: Automatic sync not happening

Diagnosis:

nextdns-blocker watchdog status

Fixes by platform:

macOS:

# Check launchd
launchctl list | grep nextdns

# Reinstall
nextdns-blocker watchdog uninstall
nextdns-blocker watchdog install

# Check logs
tail -20 ~/.local/share/nextdns-blocker/logs/cron.log

Linux:

# Check cron
crontab -l | grep nextdns

# Check cron service
systemctl status cron

# Reinstall
nextdns-blocker watchdog uninstall
nextdns-blocker watchdog install

Windows:

# Check tasks
schtasks /query /tn "NextDNS-Blocker-Sync"

# Check Task Scheduler service
Get-Service Schedule

# Reinstall
nextdns-blocker watchdog uninstall
nextdns-blocker watchdog install

API Errors

Symptoms: “API error”, “Authentication failed”, timeouts

Diagnosis:

nextdns-blocker config push --verbose

Fixes:

1. Invalid credentials

   # Re-run setup
   nextdns-blocker init

2. Timeout errors

   # Increase timeout in .env
   API_TIMEOUT=30

3. Rate limiting

   • Wait 60 seconds
   • Check RATE_LIMIT_* settings

4. Network issues

   # Test connectivity
   curl -I https://api.nextdns.io

Configuration Errors

Symptoms: “Invalid configuration”, validation failures

Diagnosis:

nextdns-blocker config validate

Common issues:

1. Invalid JSON

   # Check JSON syntax
   python3 -m json.tool ~/.config/nextdns-blocker/config.json

2. Invalid time format

   • Use HH:MM (24-hour)
   • 09:00 not 9:00
   • 18:00 not 6:00 PM

3. Invalid day names

   • Use lowercase: monday not Monday
   • Full names: wednesday not wed

4. Duplicate domains

   • Same domain can’t be in blocklist AND allowlist

Pending Actions Not Executing

Symptoms: Queued unblocks not happening

Diagnosis:

nextdns-blocker pending list
nextdns-blocker pending show <ID>

Checks:

1. Execution time not reached

   • Check “Execute at” time

2. Panic mode blocking

   nextdns-blocker panic status

3. Watchdog not running

   nextdns-blocker watchdog status

4. Force processing

   nextdns-blocker config push --verbose

Wrong Timezone

Symptoms: Schedule times don’t match expected behavior

Diagnosis:

nextdns-blocker config show | grep timezone
date  # Compare system time

Fix:

nextdns-blocker config set timezone America/New_York

Log Files

Locations

Platform	Path
macOS/Linux	~/.local/share/nextdns-blocker/logs/
Windows	%LOCALAPPDATA%\nextdns-blocker\logs\

Log Files

File	Contents
app.log	Application events
audit.log	Block/unblock actions
cron.log	Watchdog sync output
wd.log	Watchdog self-check

Viewing Logs

# Recent application logs
tail -50 ~/.local/share/nextdns-blocker/logs/app.log

# Recent sync activity
tail -50 ~/.local/share/nextdns-blocker/logs/cron.log

# Follow logs in real-time
tail -f ~/.local/share/nextdns-blocker/logs/app.log

State Files

Locations

File	Purpose	Location
.panic	Panic state	~/.local/share/nextdns-blocker/
pending.json	Pending actions	~/.local/share/nextdns-blocker/

Resetting State

Clear panic (emergency only):

rm ~/.local/share/nextdns-blocker/.panic

Reset pending actions:

echo '{"actions":[]}' > ~/.local/share/nextdns-blocker/pending.json

Complete Reset

If all else fails, reset everything:

# 1. Uninstall watchdog
nextdns-blocker watchdog uninstall

# 2. Remove state files
rm -rf ~/.local/share/nextdns-blocker/

# 3. Remove config (optional - loses settings)
rm -rf ~/.config/nextdns-blocker/

# 4. Reinstall
pip install --force-reinstall nextdns-blocker

# 5. Run setup
nextdns-blocker init

# 6. Restore config
nextdns-blocker config edit

# 7. Install watchdog
nextdns-blocker watchdog install

Getting Help

Information to Include

When reporting issues, include:

# Version
nextdns-blocker --version

# Platform
uname -a  # or systeminfo on Windows

# Status
nextdns-blocker status

# Validation
nextdns-blocker config validate

# Recent logs
tail -50 ~/.local/share/nextdns-blocker/logs/app.log

Where to Report

• GitHub Issues: github.com/aristeoibarra/nextdns-blocker/issues

Before Reporting

1. Check this troubleshooting guide
2. Search existing issues
3. Try --verbose flag for more info
4. Include relevant logs and config (redact API key!)