Rork Companion Not Connecting: Complete Debugging Guide

Rork Companion is one of the most valuable parts of the Rork workflow — real-time preview on a physical device without a build step. But when "scan QR code, see your app" turns into "connection failed" or an endless loading screen, it kills the development flow fast.

This guide breaks down connection problems into five categories with systematic troubleshooting steps for each.

How Rork Companion Connections Actually Work

Understanding the connection flow makes it much easier to identify where things are breaking.

1. Rork's web app (in your browser) starts a local server
2. A QR code or connection code is generated — this code encodes an IP address and port number
3. Rork Companion on your phone scans the QR code and connects to your computer over the local Wi-Fi network
4. App preview data is streamed to the device

The two most common failure points: the computer and phone are on different networks, or a firewall is blocking the port.

Category 1: QR Code Scanned, But "Can't Connect"

Symptoms

Rork Companion scans the QR code successfully, but shows "Can't connect," "Connection timeout," or "Server not found."

Diagnosis and fixes

Check 1: Both devices on the same Wi-Fi network

This is the most common cause. Confirm that both your computer and phone are connected to the same Wi-Fi SSID.

Watch for these situations:

• Your phone is on mobile data with Wi-Fi off
• Your computer is on Ethernet but your phone is on Wi-Fi, and they're on different network segments
• You're on a corporate or school network that blocks device-to-device communication (client isolation)

Check 2: Firewall blocking the port

Rork's local server uses TCP ports (typically in the 19000–19002 range). If your OS firewall is blocking these, the connection fails.

macOS:

1. System Settings → Privacy & Security → Firewall
2. Click Firewall Options and confirm your browser (Chrome/Safari) or Rork is set to "Allow incoming connections"
3. After confirming, regenerate the connection code in Rork

Windows:

1. Windows Security → Firewall & network protection
2. Allow an app through firewall → confirm your browser is allowed
3. Or add an inbound rule to allow TCP ports 19000–19005

Check 3: VPN interference

If either device has a VPN active, local network traffic may be routed through the VPN tunnel, breaking the local connection. Disable VPN on both devices during testing.

Category 2: Connected, But Preview Won't Load

Symptoms

Rork Companion shows "Connected" but the app preview never appears — just a white screen or a spinner that runs indefinitely.

Fixes

Cause A: Check for build errors in Rork

Open Rork in the browser and look for red error messages in the editor or console. A syntax error or import error will prevent the preview from rendering.

Common culprits:

• SyntaxError: Unexpected token — code syntax error
• Cannot read properties of undefined — null reference error
• Module not found — an import references a file that doesn't exist

Cause B: Component rendering error

If the code has no errors but the screen is white, a component may be crashing at runtime without surfacing a clear error. Check Rork's console log for runtime errors.

Cause C: Cached state in Rork Companion

Rork Companion can get stuck on a stale project state. Fully close the app (force quit from the app switcher) and reopen it, then reconnect.

Category 3: iOS-Specific Issues

Symptoms

Android Companion works fine, but iOS either can't connect or shows a broken preview.

iOS-specific fixes

Local Network permission required:

Since iOS 14, apps need explicit permission to access local network devices. When you first run Rork Companion, a dialog asks for "Local Network" access. If you denied it, the connection will always fail.

Fix: Settings → Privacy & Security → Local Network → toggle Rork to ON.

Bonjour/mDNS blocked by router:

Some routers block the Bonjour protocol (Apple's network discovery protocol), which prevents iOS devices from finding the local server.

Fix: Look for a manual IP entry option in Rork Companion's settings. If available, enter your computer's local IP address (visible in System Settings → Network) with the port number instead of using QR scanning.

Category 4: Android-Specific Issues

Symptoms

Rork Companion on Android can't connect or frequently disconnects.

Android-specific fixes

Battery optimization killing the connection:

Android's battery optimization can terminate Rork Companion's background networking, causing disconnections.

1. Settings → Apps → Rork → Battery
2. Select "Unrestricted" or "No battery optimization"

Enable Developer Options for better stability:

For development and testing work, enabling Developer Options on the device can improve performance:

1. Settings → About phone → tap Build number 7 times
2. Developer Options will be enabled
3. Turn on USB debugging (can help even over Wi-Fi connections)

Category 5: Sync Is Slow or Preview Is Laggy

Symptoms

Code changes take more than 10 seconds to appear in Rork Companion. The preview animation is choppy.

Fixes

Wi-Fi quality issues:

Rork streams code updates to Companion in real time, so Wi-Fi latency directly affects the experience.

• Connect both devices to the 5 GHz band (lower latency than 2.4 GHz)
• Move closer to the router when testing
• A Wi-Fi 6 router can make a significant difference for this kind of real-time streaming use case

Project size:

Large image or video assets in your project slow down transfers. Remove unused assets to reduce payload size.

Browser resource pressure:

Rork runs in the browser, and if your system RAM is under pressure, sync processing slows down. Close unused tabs and background apps before working in Rork.

Last Resort: When Nothing Works

If you've worked through all the above:

1. Regenerate the connection code: In Rork's Companion panel, click "Reconnect" or "Generate new code," then rescan in the app.

2. Restart both devices: Full restart of both your computer and phone, then retry.

3. Reinstall Rork Companion: Uninstall and reinstall the app on your phone. This clears any corrupt cache or settings.

4. Use a mobile hotspot: Enable a hotspot on your phone and connect your computer to it. This bypasses corporate/school network restrictions entirely.

The mobile hotspot approach is the most reliable workaround for network environments with client isolation enabled. A personal hotspot allows device-to-device communication by default, which means Rork Companion will connect almost every time in this setup.