MasterHttpRelayVPN/docs/TROUBLESHOOTING.md

Troubleshooting

Start with the symptom you see. Most problems are configuration, certificate trust, or an outdated Apps Script deployment.

Certificate Errors

Symptoms:

• Browser says the connection is not private.
• Telegram or another app works, but normal HTTPS sites do not.
• Chrome or Edge still fails after you installed the certificate.

Fix:

1. Make sure the proxy has run at least once so ca/ca.crt exists.
2. Install ca/ca.crt as a trusted root certificate.
3. Fully close and reopen the browser. On Windows, check Task Manager for background Chrome or Edge processes.
4. For Firefox, import the CA separately from Settings -> Privacy & Security -> Certificates -> View Certificates -> Authorities.

You can also run:

python main.py --install-cert

unauthorized

The shared secret does not match.

Fix:

1. Open apps_script/Code.gs.
2. Find const AUTH_KEY = "...";.
3. Make sure it exactly matches auth_key in config.json.
4. Deploy a new Apps Script deployment after changing apps_script/Code.gs.

Config not found

Run the wizard:

python setup.py

Or copy config.example.json to config.json and fill script_id plus auth_key.

502 Bad JSON

Google returned HTML or another unexpected response instead of relay JSON.

Common causes:

• Wrong Deployment ID.
• Apps Script daily quota is exhausted.
• You edited apps_script/Code.gs but did not create a new deployment.
• The deployment access setting is not Anyone.

Fix:

1. Create a new Apps Script deployment.
2. Copy the new Deployment ID into config.json.
3. Confirm the deployment is a Web App with Execute as: Me and Who has access: Anyone.
4. If quota is exhausted, wait for the quota reset or add more deployments with script_ids.

Connection Timeout

The current google_ip may be blocked or slow on your network.

Run:

python main.py --scan

Then set the recommended IP in config.json:

"google_ip": "RECOMMENDED_IP"

Restart the proxy.

Slow Browsing

Try these in order:

1. Install all dependencies from requirements.txt, especially h2.
2. Run python main.py --scan and update google_ip.
3. Deploy multiple Apps Script projects and use script_ids.
4. Keep log_level at INFO unless debugging.
5. Use an exit node only when needed, because it adds another hop.

Browser Proxy Is Set But Sites Do Not Load

Check:

1. The terminal says HTTP proxy is listening on 127.0.0.1:8085.
2. Browser proxy type is HTTP, not HTTPS.
3. HTTPS traffic is also configured to use the same HTTP proxy.
4. The CA is installed and the browser was fully restarted.

SOCKS5 Works Differently Than HTTP Proxy

Some SOCKS5 clients resolve domains locally and only send raw IPs to the proxy. That can break routes that depend on hostnames.

Use HTTP proxy 127.0.0.1:8085 for browsers and apps that support it. This is especially important for Telegram-style cases where hostname handling matters.

YouTube Opens But Video Playback Fails

Try:

"youtube_via_relay": true

Then restart the proxy. This routes YouTube through the Apps Script relay instead of the direct Google SNI-rewrite path. It may use more Apps Script executions.

If exit_node.mode is full, YouTube may also be routed through the relay so the exit node can handle all traffic.

Docker Certificate Confusion

The container generates ca/ca.crt into the host ./ca volume, but certificate installation inside the container does not trust it on your host OS.

Install ca/ca.crt manually on the host browser or OS. See Docker Guide.

Reset The Local Certificate

To remove the certificate from trust stores:

python main.py --uninstall-cert

To generate a fresh CA, stop the proxy and delete the ca/ folder. The next run will create a new one.

Never share the ca/ folder.