Troubleshooting

Common issues and solutions for BravePurifier installation and configuration.

🚨 Common Installation Issues

Permission Denied Errors

Problem: Script fails with permission denied errors

bash: ./brave-purifier.sh: Permission denied

Solution:

# Make script executable
chmod +x brave-purifier.sh

# Run with sudo
sudo ./brave-purifier.sh

Root Privileges Required

Problem: Script exits with "Root privileges required"

[ERROR] Root privileges required. Please run with sudo:

Solution:

# Always run with sudo
sudo ./brave-purifier.sh

# Or run as root
su -
./brave-purifier.sh

Package Manager Not Found

Problem: Script cannot detect package manager

[ERROR] Unsupported package manager. Supported: APT, DNF, YUM, Pacman, Zypper, Portage

Solution:

# Check if your package manager is installed
which apt || which dnf || which yum || which pacman || which zypper || which emerge

# For Arch Linux, install AUR helper first
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si

🌐 Network and Repository Issues

Repository Access Denied

Problem: Cannot access Brave repositories

[ERROR] Failed to add Brave repository

Solution:

# Check internet connection
ping -c 4 google.com

# Check DNS resolution
nslookup brave-browser-apt-release.s3.brave.com

# Try with different DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# For corporate networks, check proxy settings
export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080

GPG Key Import Failed

Problem: GPG key verification fails

[ERROR] GPG key import failed

Solution:

# Clear GPG cache
sudo rm -rf /tmp/tmp.*

# Import key manually (Debian/Ubuntu)
curl -fsSL https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg | \
    sudo gpg --dearmor -o /usr/share/keyrings/brave-browser-archive-keyring.gpg

# Import key manually (Fedora/RHEL)
sudo rpm --import https://brave-browser-rpm-release.s3.brave.com/brave-core.asc

Package Download Failed

Problem: Package download fails or times out

[ERROR] Failed to download brave-browser package

Solution:

# Update package lists
sudo apt update  # Debian/Ubuntu
sudo dnf makecache  # Fedora
sudo pacman -Sy  # Arch Linux

# Clear package cache
sudo apt clean  # Debian/Ubuntu
sudo dnf clean all  # Fedora
sudo pacman -Sc  # Arch Linux

# Retry with verbose output
sudo apt install -y brave-browser -o Debug::pkgAcquire::Worker=1

🔧 System-Specific Issues

Debian/Ubuntu Issues

Problem: Dependency conflicts

[ERROR] The following packages have unmet dependencies

Solution:

# Fix broken packages
sudo apt --fix-broken install

# Update system first
sudo apt update && sudo apt upgrade

# Install dependencies manually
sudo apt install curl gnupg

# Force package installation
sudo apt install -f brave-browser

Fedora/RHEL Issues

Problem: Repository configuration fails

[ERROR] Cannot add repository

Solution:

# Check SELinux status
getenforce

# Temporarily disable SELinux if needed
sudo setenforce 0

# Add repository manually
sudo dnf config-manager --add-repo https://brave-browser-rpm-release.s3.brave.com/brave-browser.repo

# Import key manually
sudo rpm --import https://brave-browser-rpm-release.s3.brave.com/brave-core.asc

Arch Linux Issues

Problem: AUR helper not found

[ERROR] AUR helper not found. Please install an AUR helper (yay/paru) first.

Solution:

# Install yay
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si

# Or install paru
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/paru.git
cd paru && makepkg -si

# Then run BravePurifier again
sudo ./brave-purifier.sh

openSUSE Issues

Problem: Zypper repository conflicts

[ERROR] Repository conflicts detected

Solution:

# Remove conflicting repositories
sudo zypper removerepo brave-browser

# Refresh repositories
sudo zypper refresh

# Add repository manually
sudo zypper addrepo https://brave-browser-rpm-release.s3.brave.com/brave-browser.repo brave-browser
sudo zypper --gpg-auto-import-keys refresh brave-browser

🔒 Policy and Configuration Issues

Policies Not Applied

Problem: Privacy policies don't seem to be working

[WARN] Privacy policies may not be applied correctly

Solution:

# Check if policy directory exists
ls -la /etc/brave/policies/managed/

# Verify policy file content
cat /etc/brave/policies/managed/privacy-policy.json

# Check file permissions
sudo chmod 644 /etc/brave/policies/managed/privacy-policy.json

# Restart Brave Browser completely
pkill brave-browser
brave-browser

User Settings Not Applied

Problem: User-specific settings not working

[WARN] User settings may not be applied

Solution:

# Check user config directory
ls -la ~/.config/BraveSoftware/Brave-Browser/Default/

# Verify preferences file
cat ~/.config/BraveSoftware/Brave-Browser/Default/Preferences

# Fix ownership issues
sudo chown -R $USER:$USER ~/.config/BraveSoftware/

# Remove and recreate preferences
rm ~/.config/BraveSoftware/Brave-Browser/Default/Preferences
sudo ./brave-purifier.sh

Brave Won't Start

Problem: Brave Browser fails to launch

[ERROR] Brave Browser failed to start

Solution:

# Check if Brave is installed
which brave-browser

# Try launching with debug output
brave-browser --enable-logging --log-level=0

# Check for conflicting processes
pkill brave-browser

# Reset user data
mv ~/.config/BraveSoftware ~/.config/BraveSoftware.backup
brave-browser

# Check system logs
journalctl -u brave-browser

🖥️ Display and Graphics Issues

Hardware Acceleration Problems

Problem: Brave crashes or has display issues

[ERROR] GPU process crashed

Solution:

# Disable hardware acceleration
brave-browser --disable-gpu

# Use software rendering
brave-browser --disable-gpu --disable-software-rasterizer

# Check graphics drivers
lspci | grep VGA
glxinfo | grep "direct rendering"

Wayland Compatibility

Problem: Issues on Wayland desktop environments

[ERROR] Wayland display server issues

Solution:

# Force X11 backend
brave-browser --ozone-platform=x11

# Or use Wayland native
brave-browser --ozone-platform=wayland --enable-features=UseOzonePlatform

# Check current display server
echo $XDG_SESSION_TYPE

🔍 Debugging and Diagnostics

Enable Verbose Logging

# Run script with verbose output
VERBOSE=true sudo ./brave-purifier.sh

# Enable Brave debug logging
brave-browser --enable-logging --log-level=0 --v=1

# Check system logs
sudo journalctl -f | grep brave

Collect System Information

# System information
uname -a
lsb_release -a

# Package manager version
apt --version || dnf --version || pacman --version

# Brave version
brave-browser --version

# Check dependencies
which curl gnupg

Test Installation

# Verify Brave installation
brave-browser --version

# Test policy application
brave-browser chrome://policy/

# Check settings
brave-browser chrome://settings/

# Test privacy features
brave-browser https://browserleaks.com/webrtc

🔄 Recovery and Reset

Complete Reset

If all else fails, perform a complete reset:

# Remove Brave completely
sudo apt remove --purge brave-browser  # Debian/Ubuntu
sudo dnf remove brave-browser          # Fedora
sudo pacman -Rns brave-browser         # Arch Linux

# Remove all configuration
sudo rm -rf /etc/brave/
rm -rf ~/.config/BraveSoftware/

# Remove repositories
sudo rm -f /etc/apt/sources.list.d/brave-browser-release.list  # Debian/Ubuntu
sudo rm -f /etc/yum.repos.d/brave-browser.repo                # Fedora/RHEL

# Clean package cache
sudo apt autoremove && sudo apt autoclean  # Debian/Ubuntu
sudo dnf autoremove && sudo dnf clean all  # Fedora

# Reinstall with BravePurifier
sudo ./brave-purifier.sh

Backup and Restore

# Backup current settings
cp -r ~/.config/BraveSoftware ~/.config/BraveSoftware.backup
sudo cp -r /etc/brave /etc/brave.backup

# Restore from backup
rm -rf ~/.config/BraveSoftware
cp -r ~/.config/BraveSoftware.backup ~/.config/BraveSoftware
sudo rm -rf /etc/brave
sudo cp -r /etc/brave.backup /etc/brave

📞 Getting Additional Help

Log Collection

When reporting issues, collect these logs:

# System information
uname -a > system-info.txt
lsb_release -a >> system-info.txt

# Package manager logs
sudo journalctl -u packagekit >> package-logs.txt

# Brave logs
brave-browser --enable-logging --log-level=0 2>&1 | tee brave-debug.log

# Script output
sudo ./brave-purifier.sh 2>&1 | tee purifier-output.log

Reporting Issues

When creating a GitHub issue, include:

System Information: OS, version, architecture
Error Messages: Complete error output
Steps to Reproduce: What you did before the error
Log Files: Relevant log excerpts
Expected Behavior: What should have happened

Community Support

GitHub Issues: Report bugs and issues
Discussions: Community discussions
Wiki: Documentation and guides

Emergency Contacts

For critical security issues:

Security Email: security@nightcodex7.dev
GPG Key: Available on GitHub profile

If you can't find a solution here, please create a detailed issue report on GitHub.

Troubleshooting

Troubleshooting

🚨 Common Installation Issues

Permission Denied Errors

Root Privileges Required

Package Manager Not Found

🌐 Network and Repository Issues

Repository Access Denied

GPG Key Import Failed

Package Download Failed

🔧 System-Specific Issues

Debian/Ubuntu Issues

Fedora/RHEL Issues

Arch Linux Issues

openSUSE Issues

🔒 Policy and Configuration Issues

Policies Not Applied

User Settings Not Applied

Brave Won't Start

🖥️ Display and Graphics Issues

Hardware Acceleration Problems

Wayland Compatibility

🔍 Debugging and Diagnostics

Enable Verbose Logging

Collect System Information

Test Installation

🔄 Recovery and Reset

Complete Reset

Backup and Restore

📞 Getting Additional Help

Log Collection

Reporting Issues

Community Support

Emergency Contacts

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally