Troubleshooting Guide

This document provides solutions to common issues encountered when using or developing the Secure Browser project.

Table of Contents

• Overview
• Installation Issues
• Runtime Issues
• Browser-Specific Issues
• Configuration Issues
• Network Issues
• Performance Issues
• Development Issues
• Getting Help

Overview

This guide helps you diagnose and resolve common problems with Secure Browser. Issues are categorized by type and include step-by-step solutions.

Installation Issues

Issue: Module Not Found Error

Symptom:

ModuleNotFoundError: No module named 'PyQt5'

Causes:

• Dependencies not installed
• Virtual environment not activated
• Incorrect Python version

Solutions:

1. Activate Virtual Environment

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

2. Install Dependencies

pip install -r requirements.txt

3. Verify Installation

pip list

4. Check Python Version

python --version
# Should be 3.7 or higher

Issue: PyQt5 Installation Fails

Symptom:

ERROR: Could not find a version that satisfies the requirement PyQt5

Causes:

• Incompatible Python version
• Missing system dependencies
• Network issues

Solutions:

1. Update pip

pip install --upgrade pip

2. Install System Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3-pyqt5 python3-pyqt5-dev python3-pyqt5.qtwebengine

Fedora:

sudo dnf install python3-qt5 python3-qt5-devel

macOS:

brew install pyqt5 pyqt5-webengine

3. Use Alternative Installation Method

# Install from source
pip install PyQt5 --no-binary PyQt5

Issue: tkinterweb Installation Fails

Symptom:

ERROR: Could not find a version that satisfies the requirement tkinterweb

Causes:

• Missing Tkinter development headers
• Incompatible system

Solutions:

1. Install Tkinter Development Headers

Ubuntu/Debian:

sudo apt-get install python3-tk python3-dev

Fedora:

sudo dnf install python3-tkinter python3-devel

macOS:

brew install python-tk

2. Verify Tkinter Installation

python -c "import tkinter; print('Tkinter installed')"

Issue: pywebview Installation Fails

Symptom:

ERROR: Could not find a version that satisfies the requirement pywebview

Causes:

• Missing system dependencies
• Incompatible platform

Solutions:

1. Install System Dependencies

Ubuntu/Debian:

sudo apt-get install libwebkit2gtk-4.0-dev

Fedora:

sudo dnf install webkit2gtk3-devel

macOS:

# Usually no additional dependencies needed

Windows:

# Ensure WebView2 is installed from Microsoft

2. Install with Specific Backend

pip install pywebview[gtk]
# or
pip install pywebview[qt]

Runtime Issues

Issue: Browser Window Not Appearing

Symptom:

• Command executes but no window appears
• No error messages

Causes:

• Display issues (Linux)
• GUI framework not initialized
• Virtual display not set up

Solutions:

1. Check Display Environment

echo $DISPLAY

2. Set Up Virtual Display (Linux)

sudo apt-get install xvfb
xvfb-run python main.py

3. Verify GUI Framework

python -c "from PyQt5.QtWidgets import QApplication; print('PyQt5 OK')"
python -c "import tkinter; print('Tkinter OK')"

4. Run with Verbose Output

python main.py --browser pyqt5
# Check for error messages in console

Issue: Application Crashes on Startup

Symptom:

• Application starts then immediately crashes
• Error message appears

Causes:

• Missing dependencies
• Configuration file corruption
• Incompatible libraries

Solutions:

1. Check Error Logs

python main.py 2>&1 | tee error.log

2. Reset Configuration

mv config/user_settings.json config/user_settings.json.backup
python main.py

3. Run in Debug Mode

# Add to main.py
import logging
logging.basicConfig(level=logging.DEBUG)

4. Verify Dependencies

pip check

Issue: Command-Line Arguments Not Recognized

Symptom:

error: unrecognized arguments: --browser tkinter

Causes:

• Incorrect argument syntax
• Outdated main.py
• Argument parser not configured

Solutions:

1. Check Help

python main.py --help

2. Verify main.py Configuration

# Ensure arguments are defined in main.py
parser.add_argument("--browser", choices=["pyqt5", "tkinter", "webview", "search"])

3. Use Correct Syntax

python main.py --browser tkinter
# Not
python main.py --browser=tkinter

Browser-Specific Issues

PyQt5 Browser Issues

Issue: Tabs Not Closing

Symptom:

• Clicking close tab button doesn't work
• Tab remains open

Solutions:

1. Check Signal Connection

# Verify signal is connected in hope.py
self.tabs.tabCloseRequested.connect(self.close_tab)

2. Check close_tab Method

def close_tab(self, index):
    self.tabs.removeTab(index)

3. Restart Browser

• Close and reopen the browser

Issue: Dark Theme Not Applying

Symptom:

• Browser appears with default theme
• Colors not as expected

Solutions:

1. Check StyleSheet Syntax

# Verify QSS syntax is correct
self.setStyleSheet("""
    QMainWindow {
        background-color: #2b2b2b;
    }
""")

2. Check PyQt5 Version

pip show PyQt5
# Ensure version is 5.15.0 or higher

3. Force Theme Application

app = QApplication(sys.argv)
app.setStyle('Fusion')
app.setPalette(dark_palette)

Issue: Settings Not Saving

Symptom:

• Changes in settings dialog not persisted
• Settings reset on restart

Solutions:

1. Check Dialog Return Value

if dialog.exec_():  # Only saves if OK is clicked
    self.use_vpn = dialog.vpn_checkbox.isChecked()

2. Verify Settings Are Applied

# Add debug print
print(f"VPN: {self.use_vpn}")
print(f"JavaScript: {self.enable_javascript}")

3. Implement Persistent Storage

import json

def save_settings(self):
    settings = {
        "use_vpn": self.use_vpn,
        "enable_javascript": self.enable_javascript,
        "proxy": self.proxy
    }
    with open("config/user_settings.json", "w") as f:
        json.dump(settings, f)

Tkinter Browser Issues

Issue: Pages Not Loading

Symptom:

• URL entered but page doesn't load
• Blank screen or error message

Solutions:

1. Check tkinterweb Installation

pip show tkinterweb

2. Verify URL Format

# Ensure URL has scheme
if not url.startswith(("http://", "https://")):
    url = "https://" + url

3. Check Network Connectivity

ping example.com
curl https://example.com

4. Test with Simple HTML

browser.html_frame.set_html("<h1>Test</h1>")
# If this works, issue is with URL loading

Issue: Website Filtering Not Working

Symptom:

• Blacklisted/whitelisted sites still accessible
• Filtering rules not applied

Solutions:

1. Verify Filter Configuration

print(f"Whitelist: {browser.whitelist}")
print(f"Blacklist: {browser.blacklist}")

2. Check URL Matching Logic

# Ensure prefix matching is correct
if any(url.startswith(blocked) for blocked in self.blacklist):
    # Block the site

3. Test Filter Application

# Add debug output
print(f"Checking URL: {url}")
print(f"Matches blacklist: {any(url.startswith(b) for b in self.blacklist)}")

4. Reload After Configuration

# Settings may require page reload
self.reload_page()

Issue: JavaScript Still Executing When Disabled

Symptom:

• JavaScript runs despite being disabled
• Scripts execute on pages

Solutions:

1. Verify JavaScript Toggle

print(f"JavaScript enabled: {self.javascript_var.get()}")

2. Check Content Filter

if not enabled:
    self.html_frame.set_content_filter(lambda content: None)
else:
    self.html_frame.set_content_filter(None)

3. Reload Page After Toggle

self.toggle_javascript()
self.reload_page()

4. Note on Limitations

• tkinterweb may have limited JavaScript control
• Some scripts may still execute

WebView Browser Issues

Issue: WebView Window Not Opening

Symptom:

• Tkinter controls appear but webview window doesn't
• No error message

Solutions:

1. Check pywebview Installation

pip show pywebview

2. Verify Backend

import webview
print(f"Backend: {webview.get_backend()}")

3. Try Different Backend

webview.create_window("Test", "https://example.com", backend="qt")
# or
webview.create_window("Test", "https://example.com", backend="gtk")

4. Check System Dependencies

# Linux: webkit2gtk
# Windows: WebView2
# macOS: WebKit (built-in)

Issue: URL Not Loading in WebView

Symptom:

• URL entered but webview doesn't navigate
• Stays on previous page

Solutions:

1. Check URL Format

if not url.startswith(("http://", "https://")):
    url = "http://" + url  # WebView may need http

2. Verify load_url Call

webview.load_url(url)

3. Check for Errors

try:
    webview.load_url(url)
except Exception as e:
    print(f"Error: {e}")

4. Restart Application

• WebView may need restart to apply changes

Configuration Issues

Issue: Configuration File Not Found

Symptom:

FileNotFoundError: [Errno 2] No such file or directory: 'config/user_settings.json'

Solutions:

1. Create Configuration Directory

mkdir -p config

2. Create Default Configuration

cat > config/user_settings.json << EOF
{
  "home_url": "https://search.brave.com/",
  "security": {
    "https_enforcement": true,
    "javascript_enabled": true,
    "whitelist": [],
    "blacklist": []
  },
  "proxy": {
    "http": "",
    "https": ""
  }
}
EOF

3. Check File Path

ls -la config/user_settings.json

Issue: Invalid JSON in Configuration

Symptom:

json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes

Solutions:

1. Validate JSON

python -m json.tool config/user_settings.json

2. Fix JSON Syntax

{
  "home_url": "https://example.com",
  "security": {
    "https_enforcement": true
  }
}

3. Use JSON Validator

• Use online JSON validator
• Check for trailing commas
• Ensure quotes are double quotes

Issue: Settings Not Persisting

Symptom:

• Settings changes lost after restart
• Configuration file not updated

Solutions:

1. Check File Permissions

ls -la config/user_settings.json

2. Ensure Write Access

chmod 644 config/user_settings.json

3. Implement Save Function

import json

def save_config(self):
    config = {
        "home_url": self.home_url,
        "security": {
            "https_enforcement": True,
            "javascript_enabled": self.javascript_var.get()
        }
    }
    with open("config/user_settings.json", "w") as f:
        json.dump(config, f, indent=2)

4. Call Save on Settings Change

def set_security_settings(self):
    # ... apply settings ...
    self.save_config()

Network Issues

Issue: Pages Not Loading (Network Error)

Symptom:

• All pages fail to load
• Network error messages

Solutions:

1. Check Internet Connection

ping -c 4 google.com
curl https://example.com

2. Check Firewall

# Linux
sudo ufw status

# Windows
# Check Windows Firewall settings

3. Disable Proxy Temporarily

unset http_proxy
unset https_proxy

4. Test with Different Site

curl https://www.google.com

Issue: Proxy Not Working

Symptom:

• Proxy configured but traffic not routed
• Direct connection still used

Solutions:

1. Verify Proxy URL Format

# Correct format
http://proxy.example.com:8080
http://username:password@proxy.example.com:8080

2. Test Proxy with curl

curl -x http://proxy.example.com:8080 https://example.com

3. Check Environment Variables

echo $http_proxy
echo $https_proxy

4. Verify Proxy Server

• Check proxy server is running
• Check proxy server logs
• Test proxy with another application

Issue: HTTPS Certificate Errors

Symptom:

• SSL certificate errors
• Pages not loading due to certificate issues

Solutions:

1. Check System Time

date
# Ensure system time is correct

2. Update Certificate Store

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ca-certificates
sudo update-ca-certificates

macOS:

# Certificates usually updated with OS updates

Windows:

# Update certificates via Windows Update

3. Disable Certificate Verification (Not Recommended)

# Only for testing
import ssl
ssl._create_default_https_context = ssl._create_unverified_context

Performance Issues

Issue: Browser Running Slowly

Symptom:

• Pages load slowly
• UI is unresponsive

Solutions:

1. Check System Resources

# Linux
top
htop

# Windows
Task Manager

# macOS
Activity Monitor

2. Close Unnecessary Tabs

• Reduce number of open tabs
• Each tab consumes memory

3. Clear Cache

# Clear browser cache if applicable
# Implementation depends on browser backend

4. Disable JavaScript

• JavaScript can slow down page loading
• Disable if not needed

Issue: High Memory Usage

Symptom:

• Browser consumes excessive memory
• System slows down

Solutions:

1. Monitor Memory Usage

# Linux
ps aux | grep python

# Check memory per tab/process

2. Use Lighter Browser Backend

• Tkinter browser uses less memory
• Consider switching from PyQt5 to Tkinter

3. Restart Browser Regularly

• Memory leaks may accumulate
• Restart periodically

4. Limit Tab Count

• Keep fewer tabs open
• Close tabs when not needed

Issue: High CPU Usage

Symptom:

• Browser consumes high CPU
• Fan runs constantly

Solutions:

1. Identify Resource-Intensive Pages

• Check which pages cause high CPU
• Close those pages

2. Disable Extensions

• Extensions may cause high CPU
• Disable unnecessary extensions

3. Update Browser Engine

• Ensure PyQtWebEngine is up to date

pip install --upgrade PyQtWebEngine

4. Check for Infinite Loops

• Review custom code for loops
• Add timeout to long-running operations

Development Issues

Issue: Import Errors in Development

Symptom:

ImportError: cannot import name 'Browser' from 'src.browsers'

Causes:

• Module not exported
• Circular imports
• Incorrect import path

Solutions:

1. Check Module Exports

# src/browsers/__init__.py
from .hope import Browser
from .secure_browser import SimpleBrowser as SecureBrowser
from .modern_browser import SimpleBrowser as ModernBrowser

2. Check Import Path

# Correct
from src.browsers import Browser

# Incorrect
from browsers import Browser
from src.browsers.hope import Browser

3. Check PYTHONPATH

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

4. Run from Project Root

# Run from project directory, not subdirectory
python main.py
# Not
cd src && python ../main.py

Issue: Tests Failing

Symptom:

• Tests fail with errors
• Unexpected test results

Solutions:

1. Run Tests with Verbose Output

pytest -v
pytest -vv

2. Run Specific Test

pytest tests/test_browsers/test_secure_browser.py::test_https_enforcement

3. Check Test Isolation

• Ensure tests don't depend on each other
• Use fixtures for setup/teardown

4. Debug Test Failure

pytest --pdb

5. Update Test Expectations

• Test may need updating for new features
• Review test logic

Issue: Code Style Errors

Symptom:

flake8: E501 line too long
black: reformatted code

Solutions:

1. Auto-format with Black

black src/

2. Fix Flake8 Errors

flake8 src/
# Fix reported issues manually

3. Configure Line Length

# In .flake8 or setup.cfg
[flake8]
max-line-length = 100

4. Ignore Specific Errors

flake8 src/ --ignore=E501,W503

Issue: Documentation Build Errors

Symptom:

• Documentation fails to build
• Missing references

Solutions:

1. Check Markdown Syntax

• Use markdown linter
• Validate links

2. Check Code References

• Ensure code examples are correct
• Verify API references exist

3. Build Documentation Locally

# If using Sphinx or similar tool
make docs

Getting Help

Diagnostic Information Collection

Before seeking help, collect the following information:

1. System Information

python --version
pip list
uname -a  # Linux/macOS
# or
systeminfo  # Windows

2. Error Messages

• Copy full error traceback
• Include console output

3. Configuration

cat config/user_settings.json

4. Steps to Reproduce

• Document exact steps
• Include minimal example if applicable

Reporting Issues

When reporting issues, include:

1. Clear Title

   • Descriptive and concise
   • Include component name

2. Description

   • What you were trying to do
   • What happened instead
   • Expected behavior

3. Environment

   • OS and version
   • Python version
   • Browser backend used

4. Steps to Reproduce

   • Minimal reproduction steps
   • Code examples if applicable

5. Error Messages

   • Full traceback
   • Console output

6. Additional Context

   • Screenshots if applicable
   • Configuration files
   • Related issues

Community Resources

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and discuss ideas
• Documentation: Check existing documentation first
• Code Examples: Review similar implementations

Common Solutions Quick Reference

Issue	Quick Fix
Module not found	pip install -r requirements.txt
Browser won't start	Check display environment
Settings not saving	Verify file permissions
Pages not loading	Check network connection
Proxy not working	Test proxy with curl
High memory usage	Close tabs, restart browser
Import errors	Check PYTHONPATH
Tests failing	Run with verbose output

Additional Resources

Debugging Tools

• pdb: Python debugger
• logging: Python logging module
• print(): Simple debugging
• IDE Debugger: VS Code, PyCharm debuggers

System Monitoring

• htop: System monitor (Linux)
• Activity Monitor: System monitor (macOS)
• Task Manager: System monitor (Windows)
• netstat: Network connections

Log Files

Check application logs for detailed error information:

# Application logs
tail -f browser.log

# System logs
journalctl -u python
# or
tail -f /var/log/syslog

Conclusion

This troubleshooting guide covers the most common issues encountered with Secure Browser. If you continue to experience problems after trying these solutions, please collect the diagnostic information and report the issue through the appropriate channels.

Remember that many issues can be resolved by:

• Ensuring dependencies are properly installed
• Verifying configuration files
• Checking system resources
• Running the latest version of the software