Connection Issues

Can't connect? Here's how to diagnose and fix connection problems.

Quick Diagnostics

Run these commands to check your setup:

bash

# Pairing path (token + TLS + QR readiness)
broski doctor --profile pairing

# Network path (IP + port + Tailscale)
broski doctor --profile network

# Apply safe automatic fixes
broski doctor --fix

# Export diagnostics bundle
broski doctor --export

Connection States

Understanding how the connection state machine works:

DISCONNECTED

↓ connect()

CONNECTING

↓ success

timeout/error ↗

CONNECTED

↓ disconnect() or network change

RECONNECTING→ retry → CONNECTING

State	What It Means	User Action
Disconnected	No active connection	Tap to connect or scan QR code
Connecting	Establishing WebSocket connection	Wait a few seconds
Connected	Active connection, ready to use	None needed
Reconnecting	Connection lost, auto-retry in progress	Wait for auto-reconnect

Cannot Connect to Bridge

Symptom

App shows "Disconnected" or "Connection failed"

Is the bridge running?

bash

# Background service status
broski status

# If not running, start bridge
broski

Is the bridge healthy?

bash

broski doctor --profile pairing
broski doctor --profile network

Are you on the same network?

For local connections, both devices must be on the same WiFi. Check your phone's WiFi settings.

Is the firewall blocking connections?

bash

# macOS: Check firewall status
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Windows: Check firewall status
netsh advfirewall show allprofiles state

# Linux (UFW): Check firewall status
sudo ufw status

Is the auth token correct?

Re-scan the QR code to get a fresh token. To regenerate: run broski --new-token, then broski qr to display the new QR code.

Solutions by Cause

Cause	Solution
Bridge not running	`broski`
Wrong network	Connect phone to same WiFi as computer
Firewall blocking	Add exception for port 18274
Token mismatch	Run broski --new-token to regenerate, then broski qr to re-scan
Stale connection	Force quit app and reconnect

Port Already in Use

Error Message

Bridge port 18274 is already in use.

Diagnosis

bash

# macOS/Linux: Find what's using the port
lsof -nP -iTCP:18274 -sTCP:LISTEN

# Windows: Find what's using the port
netstat -ano | findstr :18274

# Example output (macOS/Linux):
# COMMAND   PID   USER   FD   TYPE   DEVICE
# broski-b  1234  user   12u  IPv4   0x1234

Solutions

Option 1: Kill the existing process

bash

# macOS/Linux: Get the PID from lsof output, then:
kill <PID>

# macOS/Linux: Or kill all processes on the port:
lsof -nP -iTCP:18274 -sTCP:LISTEN | awk 'NR>1 {print $2}' | xargs kill

# Windows: Get the PID from netstat output, then:
taskkill /PID <PID> /F

Option 2: Suspended process (Ctrl+Z issue)

If you accidentally pressed Ctrl+Z instead of Ctrl+C:

bash

# List suspended jobs
jobs

# Bring to foreground and stop properly
fg
# Then press Ctrl+C

Option 3: Use a different port

bash

# Random free port
broski --port 0

# Specific port
broski --port 18275

Heartbeat / Ping-Pong

The bridge uses a heartbeat mechanism to detect dead connections:

Parameter	Value	Purpose
Bridge ping interval	20 seconds	Server-initiated keepalive
App ping interval	15 seconds	Client-initiated keepalive
Pong timeout	10 seconds	Max wait for response
Dead connection	90 seconds	No response = disconnect

How it works

The bridge sends a ping every 20 seconds. If no pong response is received within 90 seconds, the connection is considered dead and closed. The app will then attempt to reconnect automatically.

bash

# Follow bridge logs for heartbeat/connectivity issues
broski logs --follow

Connection Keeps Dropping

Symptoms

Disconnects every few minutes, "Heartbeat timeout" in logs, constant reconnecting indicator

Cause	Diagnosis	Solution
Network instability	Check WiFi signal strength	Move closer to router or use wired
High latency	RTT > 200ms in app	Switch to local connection
WiFi switching	Phone auto-switching networks	Lock WiFi network in phone settings
Background app killing	iOS/Android battery saving	Disable battery optimization for Broski
Server heartbeat timeout	Bridge logs show timeout	Restart bridge

Firewall Configuration

macOS

GUI Method

System Settings → Network → Firewall
Click "Options..."
Add the broski binary to allowed applications
Or enable "Automatically allow built-in software"

Terminal Method

bash

# Check firewall status
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Add exception for Broski
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which broski)

# Or disable firewall temporarily (not recommended for production)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

Windows

Open Windows Security → Firewall & network protection
Click "Allow an app through firewall"
Add broski.exe or allow port 18274
Ensure both Private and Public are checked

Linux (UFW)

bash

# Allow bridge port
sudo ufw allow 18274/tcp

# Check status
sudo ufw status

Linux (firewalld)

bash

# Allow bridge port
sudo firewall-cmd --permanent --add-port=18274/tcp
sudo firewall-cmd --reload

# Check status
sudo firewall-cmd --list-ports

QR Code Scanning Issues

Issue	Solution
Camera won't focus	Ensure adequate lighting, clean camera lens
Code too small	Move closer or increase terminal font size
Invalid QR error	Regenerate with broski --new-token
Partial scan	Hold phone steady for 2-3 seconds
Old QR code	Token may have changed, regenerate

Manual Connection Alternative

If QR scanning fails, connect manually:

In the app, go to Settings → Connection → Manual Connect
Enter the bridge URL shown in terminal

text

wss://192.168.1.x:18274?token=YOUR_TOKEN

Still having issues?

Collect this debug info before contacting support:

bash

broski --version
broski doctor --profile pairing
broski doctor --export

Email: broskiappp@gmail.com