Troubleshooting

This document provides guidance for diagnosing and resolving common issues encountered while setting up and using GeekEZ Browser. It covers problems related to initial installation, profile launching, network connectivity, and data management.

Installation and Setup

Issues during the npm install phase are typically related to the postinstall script defined in package.json, which executes setup.js. This script is responsible for downloading the required Xray-core and Chromium binaries.

Sources: package.json:9, setup.js

Dependency Download Failures

The setup.js script automatically detects network conditions to decide whether to use a GitHub proxy for downloads. Failures at this stage usually manifest as errors in the terminal during npm install.

Sources: setup.js:108-112

The setup process follows this general flow:

This diagram illustrates the automated download and setup process initiated by npm install.
Sources: setup.js:104-149

Common Causes & Solutions:

1. Network Instability: The script may fail if there is no internet connection or if the connection to GitHub (or its mirror) is unstable.
   • Solution: Ensure you have a stable internet connection and try running npm install again.
2. Extraction Errors: The script uses unzip (Linux/macOS) or powershell (Windows) to extract binaries.
   • Solution: Ensure these system commands are available in your PATH. If extraction fails, manually delete the resources/bin and resources/puppeteer directories and re-run npm install.
     Sources: setup.js:90-102
3. Incorrect Binary Path: After setup, the application expects to find xray.exe (or xray) in the resources/bin directory.
   • Solution: Verify that the binary exists at the expected path. The path is determined based on the operating system.
     Sources: main.js:15-16, setup.js:59-73

Profile Launch Failures

A profile launch can fail at several stages, from generating configuration files to spawning the browser process. The entire launch sequence is orchestrated by the launch-profile IPC handler in main.js.

Sources: main.js:332-468

Launch Sequence

The following diagram shows the sequence of events when a user clicks the "Launch" button for a profile.

Common Failure Points

| Error / Symptom | Potential Cause - Error: "Chrome binary not found." | The path to the Chromium executable could not be resolved. This happens if the setup.js script failed to download or place the browser correctly. - Solution: Run node setup.js manually from the project root to re-download dependencies. Check the resources/puppeteer directory for the Chrome executable. Sources: main.js:424-427, main.js:41-61 |
| Browser window opens and closes immediately | The Xray process likely failed to start or the proxy connection was refused. Check the xray_run.log inside the specific profile's data directory. - Solution: Check the proxy link format in the profile settings. Use the "Test" button in the proxy manager to verify connectivity. Sources: main.js:400-403, renderer.js:905-913 |
| Profile is stuck in "RUNNING" state | The browser process may have crashed, but the main process did not receive the disconnected event, leaving a stale entry in activeProcesses. - Solution: Restart the GeekEZ Browser application. The app is designed to clean up all active processes on shutdown. Sources: main.js:469-472 - Browser cleanup: Upon disconnection, the browser cache is automatically cleared to save disk space. If this fails, the profile's data directory may grow over time. Sources: main.js:456-463 |

Network and Proxy Issues

Network problems are often related to incorrect proxy configurations or issues with the Xray-core process.

Proxy Latency Test

The application provides a feature to test the latency of a proxy. This is handled by the test-proxy-latency IPC event.

This diagram shows the steps involved in testing a single proxy's latency.
Sources: main.js:106-135, renderer.js:905-913

• Failure Point: If the proxy string is malformed, the test will fail immediately.
• Timeout: The test has a 5-second timeout. A "Timeout" result indicates the proxy is either down or too slow.
• Log Files: The main Xray process for a launched profile logs to xray_run.log within the profile's data directory. This file is essential for debugging connection issues that occur after a successful launch.
  Sources: main.js:402

Data and Configuration

The application's state is stored in several JSON files within the user data directory. Corruption or incorrect permissions on these files can cause issues.

Key File Locations

The main process defines several critical paths for storing application data.

This diagram shows the directory structure for profiles and settings.
Sources: main.js:17-22, main.js:270-276, main.js:401-402

Import/Export Issues

Data import/export uses the YAML format. Issues can arise from malformed files.

• Import Failure: The app may fail to import a .yaml file if the structure is incorrect. The importer looks for top-level keys like profiles, preProxies, and subscriptions. If these are missing or data is malformed, the import may partially or completely fail.
  Sources: main.js:300-330
• No Data to Export: The "Export" function will show a "No data found to export" message if there are no profiles or proxy settings to save.
  Sources: renderer.js:833-837