Troubleshooting

Startup Issues

Error: EADDRINUSE (Port Already in Use)

Full error message:

Error: listen EADDRINUSE: address already in use :::7788

Cause: Sidecar WebSocket server port 7788 is occupied

Solutions:

Method 1: Force kill via Task Manager

Ctrl+Shift+Esc → Details
Find all chrome.exe → Right-click → End task
Find all electron.exe → Right-click → End task

Method 2: Kill processes via command line

taskkill /F /IM chrome.exe
taskkill /F /IM electron.exe

Method 3: Check port usage

netstat -ano | findstr :7788
taskkill /F /PID <ProcessID>

Chrome Download Fails on First Launch

Symptoms: Progress bar stuck at 0% or network error reported

Solutions:

Check network connection
```
ping api.linege.com
```
Disable firewall/antivirus software
- Temporarily disable Windows Defender
- Temporarily disable third-party antivirus software

Manually download Chrome core

Download URL: https://api.linege.com/download/chrome/latest
Extract to: %APPDATA%\Linege\core\

Check disk space
- Chrome core requires approximately 500MB of space
- Ensure the C:\Users\<username>\AppData\Roaming\Linege directory is writable

Self-Test Failure

Symptoms: Auto-test of 4 browsers fails after startup

Troubleshooting steps:

Check logs

Open: %APPDATA%\Linege\logs\main.log
Search for: [CRITICAL] or [ERROR]

Common errors:
- CreateBrowserWindow failed: Incorrect Chrome path
- WebSocket connection timeout: Sidecar not started
- Port 9222 occupied: CDP port is occupied
Manual test
- Skip the auto-test, manually create an environment and launch
- If launch succeeds, it's an auto-test script issue and can be ignored

Connection Issues

Browser Cannot Connect to Sidecar After Launch

Symptoms: Browser status shows Active, but group control is not working

Troubleshooting steps:

Check profile.json

Location: %APPDATA%\Linege\data\<env_id>\profile.json

Must contain:
{
  "profileId": "...",
  "envId": "..."  ← Must exist
}

If envId is missing:

{
  "profileId": "env_xxx_profile",
  "envId": "env_xxx"
}

Check WebSocket connection
- Open browser DevTools (F12)
- Console tab
- Search for WebSocket or ws://localhost:7788
- Should display WebSocket connection established
Check Chrome extension
- Visit chrome://extensions/
- Confirm the Linege extension is loaded
- Check if the extension has any errors

WebSocket Connection Timeout

Error message:

WebSocket connection to 'ws://localhost:7788' failed

Solutions:

Check if Sidecar is running

Main process log should contain:
[SidecarServer] Server started on port 7788

Check firewall rules

Windows Settings → Firewall → Allow an app
Add: Linege.exe
Allow: Private network + Public network

Check hosts file

C:\Windows\System32\drivers\etc\hosts

Ensure it contains:
127.0.0.1  localhost

Group Control Issues

Master Browser Actions Not Syncing to Slave Browsers

Troubleshooting checklist:

1. Is group control enabled?

Check: Does the app border have an amber highlight?
Check: Does the left button show "Group Control On"?

2. Is the master browser window in the foreground?

Issue: Master browser window is minimized or covered
Solution: Click the master browser window to bring it to the front

3. Are all browsers connected to Sidecar?

Check: Does the browser Console show a WebSocket connection?
Check: Does the log contain "Linege browser connected" entries?

4. Are Master/Slave roles correct?

Log should show:
[SidecarServer] Master elected: <profile_id>
[Chrome] Role: Master  ← First browser launched
[Chrome] Role: Slave   ← Subsequently launched browsers

Paste (Ctrl+V) Not Syncing

Cause: Paste detection fails in Windows RDP remote desktop sessions

Solutions:

Test on a local machine
- Clipboard events may not be captured in RDP sessions
Trigger paste manually
- Right-click → Paste in the master browser
- Or use the text group input feature for batch filling

Scroll Wheel Sync Not Working

Cause 1: RawInput Hook not started

Check logs:

[SidecarServer] Mouse wheel hook spawned: <script_path>
[SidecarServer] Mouse wheel hook ready

Cause 2: Windows Server RDP environment

Known limitations:

Low-level hooks (WH_MOUSE_LL) do not work in Windows Server remote desktop
RawInput API is used as an alternative, but requires foreground window focus

Solutions:

Test on a local Windows 10/11 machine
Or use a physical machine instead of a virtual machine

Text Input Issues

Clicking "Sequential Input" Has No Response

Troubleshooting steps:

1. Is the text group empty?

Check: The text box must have at least one non-empty line

2. Are all browsers launched?

Check: Is the environment status Active (green)?
Count: Number of text lines ≤ Number of launched browsers

3. Is the selector correct?

Default: Leave empty (uses :focus for auto-focus)
Custom: Ensure the selector exists on the page (e.g., #username)

4. Check logs

Log should show:
[SidecarServer] distribute_text_sequential ENTER
[SidecarServer] distribute_text_sequential SENT, i=0, targetProfile=...

Window Arrangement Issues

Window Arrangement Order Is Not 1-2-3-4

Cause: Window order is based on launch time (PID)

Solutions:

Method 1: Launch in order

1. Launch the 1st browser first
2. Wait for it to fully start (status changes to Active)
3. Then launch the 2nd one
4. And so on...

Method 2: Check PIDs

Task Manager → Details → Sort by PID
The smallest PID is the 1st window

Performance Issues

CPU Usage at 100%

Scenario 1: First time opening a large website (normal)

Symptoms: CPU hits 100% when opening sites like Poly, lasting 20-30 seconds
Cause: Page loading, JavaScript initialization, resource downloading
Solution: Wait for the page to fully load and CPU will return to normal

Scenario 2: Running too many browsers simultaneously

Symptoms: CPU stays high after launching 10+ browsers
Solutions:
  - Launch in batches (4-6 per batch)
  - Close unused browsers
  - Upgrade hardware (16GB RAM recommended)

High Memory Usage

Normal usage:

Single browser: 300-500MB
10 browsers: 3-5GB

Proxy Issues

Proxy Connection Failed

Error messages:

ERR_PROXY_CONNECTION_FAILED
ERR_TUNNEL_CONNECTION_FAILED

Troubleshooting steps:

Check proxy format

Correct: http://user:pass@192.168.1.100:8080
Wrong: 192.168.1.100:8080  ← Missing protocol
Wrong: http://192.168.1.100  ← Missing port

Check proxy server

curl -x http://user:pass@ip:port https://ip-api.com/json

Check proxy authentication

Is the username/password correct?
Does it contain special characters? (URL encoding required)

Log Analysis

Log Locations

%APPDATA%\Linege\logs\
├── main.log          # Main process log (IPC, startup, Sidecar)
├── renderer.log      # Renderer process log (React UI)
└── sidecar.log       # WebSocket server log (group control, text input)

Key Log Markers

Error levels:

[CRITICAL]  # Fatal error (app crash)
[ERROR]     # Error (feature failure)
[WARN]      # Warning (recoverable issue)
[INFO]      # Information (normal flow)
[DEBUG]     # Debug information

Key process markers:

[LAUNCH]             # Browser launch process
[SidecarServer]      # WebSocket server
[IPC]                # Inter-process communication
[Chrome]             # Chrome extension
[STATE_INVALID]      # Invalid state

Full Reset (Last Resort)

If all methods fail, you can perform a full reset:

WARNING: This will delete all data. Please back up beforehand.

Steps:

Close the application
```
Task Manager → End Linege.exe
```

Back up important data (optional)

Back up: %APPDATA%\Linege\data\<env_id>\

Delete the data directory
```
Delete: %APPDATA%\Linege
```

Restart the application

The app will reinitialize and download Chrome core

Contact Support

If none of the above methods resolve your issue, please contact technical support with the following information:

System info: Win+R → winver
App version: Settings → About
Log files: %APPDATA%\Linege\logs\
Reproduction steps: Detailed description of actions + screenshots/screen recordings

Troubleshooting

目录