Troubleshooting & Diagnostics

Local Bridge is designed to stay out of the way. When something goes wrong, the built-in Doctor command and explicit exit codes help you isolate the issue quickly.

Running the Doctor Command

If you are experiencing unexpected behavior, the first step is to run the built-in diagnostic tool:

> localbridge doctor

This command will verify your local file permissions, tunnel binary cache integrity, port availability, and registry health. Most problems can be diagnosed here.

Common Errors

Port Already in Use

By default, Local Bridge binds to port 8080. If another application is occupying this port, you will see an Exit Code 1.

Solution: Specify a custom port via the --port flag:

> localbridge --port 9000 .\folder

Tunnel Setup Timeout (502/503)

Occasionally, the Cloudflare edge network may take longer than expected to fully propagate routing for your tunnel, resulting in a temporary HTTP 500-level error when accessing the provided URL.

Solution: The CLI actively polls the edge node for readiness. Give it another 10-15 seconds and refresh the browser URL.

Windows SmartScreen Warning

Windows may show a SmartScreen filter warning when running the binary for the first time.

Solution: Click "More info" then "Run anyway". This is expected behavior for unsigned executables and does not indicate a security risk.

Exit Codes Reference

Local Bridge uses strict exit codes so you can safely integrate it into CI/CD pipelines and shell scripts.

Code	Meaning	When it happens
0	Success	Command completed successfully.
1	Port In Use	The specified port is already bound to another process.
2	Invalid Arguments	Missing flags, unrecognized commands, or bad syntax.
3	Permission Denied	CLI lacks OS permissions to read the target directory.
4	Cloudflare Error	The tunnel handshake failed or timed out.
5	Not Found	Attempted to stop or inspect a share that does not exist.
6	Already Running	A share with that --name is already active.
7	Network Error	Cannot reach the licensing server for validation.
10	Generic Failure	An unexpected internal error occurred.

Script Integration

Use the deterministic exit codes above to safely orchestrate persistent background shares within automated jobs.

PowerShell

localbridge --bg .
if ($LASTEXITCODE -eq 1) {
    Write-Host "Port in use! Trying fallback port..."
    localbridge --bg --port 9000 .
} elseif ($LASTEXITCODE -eq 6) {
    Write-Host "Daemon already running. Skipping."
} else {
    Write-Host "Failed with code $LASTEXITCODE"
    exit 1
}

Need Human Support?

If these troubleshooting steps do not resolve your issue, please navigate to your Whop dashboard and open a direct chat with our support team.