docs/guides/WEB_TROUBLESHOOTING.md

Web Interface Troubleshooting

HTTP 403 Error

If you see "Access to localhost was denied" or HTTP 403:

Solution 1: Use 127.0.0.1 instead of localhost

Try accessing:

http://127.0.0.1:5001

Instead of:

http://localhost:5001

Solution 2: Check if server is running

# Check if server is running
ps aux | grep web_app

# Or test the server
python3 test_server.py

Solution 3: Clear browser cache

• Hard refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
• Or try incognito/private mode

Solution 4: Check firewall settings

On macOS:

• System Settings → Network → Firewall
• Make sure Python/Flask is allowed

Solution 5: Try a different port

The app auto-detects ports 5000-5009. If 5001 doesn't work, try:

• Check what port the server actually started on (shown in terminal)
• Or manually set a port in web_app.py

Server Not Starting

Error: "Address already in use"

# Kill any process on the port
lsof -ti:5001 | xargs kill -9

# Or use a different port
FLASK_RUN_PORT=5002 python3 web_app.py

Error: "ModuleNotFoundError: No module named 'flask'"

# Install Flask
pip3 install flask

# Or use venv
source venv/bin/activate
pip install flask

Quick Test

Run this to test if server is accessible:

python3 test_server.py

This will test both 127.0.0.1 and localhost URLs.

Still Having Issues?

1. Check server logs: Look at the terminal where you ran python3 web_app.py
2. Try curl: curl http://127.0.0.1:5001/health
3. Check browser console: Open Developer Tools (F12) and check for errors
4. Try different browser: Chrome, Firefox, Safari