If you've ever opened Rork Companion only to stare at a blank screen, a spinning loader, or an error message after scanning the QR code, you're not alone. These issues are frustrating — but they almost always come down to a handful of well-known causes.
What Rork Companion Actually Does
Rork Companion is the app that bridges your Rork project and your physical iOS or Android device. When you scan the QR code shown in the Rork editor, Companion connects over your local Wi-Fi network and streams your app in real time — changes you make in the editor show up on your phone within seconds.
Because it relies on local networking, the connection is sensitive to three things: your Wi-Fi setup, app versions, and the health of your project code. When any of these is off, Companion struggles.
Problem 1: Companion Won't Connect
Check your network first. This is the single most common cause.
- Your development machine (PC or Mac) and your phone must be on the same Wi-Fi network. Mobile data (4G/5G) won't work. Public Wi-Fi networks — cafés, libraries, coworking spaces — often block device-to-device communication, so connecting from home or using a personal hotspot is strongly recommended.
- Some routers have AP Isolation (also called "client isolation") enabled for security. This feature prevents devices on the same network from talking to each other. Disabling AP Isolation in your router settings usually resolves the issue immediately.
Check your Companion app version. If your Companion app is significantly out of date compared to the Rork web app, the QR code format may not match. Update Companion from the App Store or Google Play before trying again.
If things still aren't working, try this reset sequence:
1. Reload your Rork project page (Cmd+R or F5 in the browser)
2. Force-quit Companion on your phone (swipe it away from the app switcher)
3. Relaunch Companion
4. Scan the QR code again
That simple sequence resolves the majority of "can't connect" cases.
Problem 2: Preview Is Blank or Stuck Loading
You scanned the QR code successfully, but the preview never appears — just a white screen or an endless spinner. In this case, the problem is almost certainly in your project code, not the connection itself.
Look for errors in the Rork editor. Red error messages in the editor console or the bottom panel indicate a code problem that's preventing the app from rendering. Fix those first, then try the preview again.
One of the most common culprits is an empty JSX return:
// ❌ Broken: empty return causes a blank screen
export default function MyScreen() {
return (
// nothing here — Companion shows a white screen
);
}
// ✅ Fixed: return at least a basic element
export default function MyScreen() {
return (
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text>Hello, Rork\!</Text>
</View>
);
}External resources can also cause blank screens. If your app tries to load images or data from a remote URL and that request fails (due to a slow or restricted network), Companion may hang. Try stripping out external resources temporarily to confirm the rest of the app renders correctly.
Stale cache is another possibility. Use the Rork editor to regenerate or reload your project, then reconnect from Companion.
Problem 3: Companion Keeps Crashing
Crashes typically come from one of three sources:
Low device memory. Running many apps in the background leaves little memory for Companion. Close unused apps, then relaunch Companion.
An outdated version of Companion. Older builds can have crashing bugs that have since been patched. Updating to the latest version is always worth trying first.
An infinite loop or expensive operation in your code. A poorly configured useEffect is a classic offender:
// ❌ Infinite loop: updates state, which triggers the effect, which updates state...
useEffect(() => {
fetchData();
}, [data]); // re-runs every time `data` changes, which fetchData causes
// ✅ Run only on mount
useEffect(() => {
fetchData();
}, []); // empty array = runs onceIf you're not sure where the problem is, ask Rork's AI to review your code for performance issues — it's good at catching these patterns.
A Note on Rork Max (Native iOS Apps)
If you're working on a Rork Max project, Companion doesn't apply. Rork Max generates native Swift/SwiftUI apps that must be compiled via Cloud Compile and then distributed through TestFlight or direct device installation.
This trips up a lot of users who expect the same quick-preview workflow from standard Rork projects. For Rork Max, the preview pipeline is different by design. Check out Rork Companion iOS Real Device Testing Guide for the full details on the distinction.
Quick Troubleshooting Checklist
Before spending more time debugging, run through this list:
- Same Wi-Fi: Both your computer and phone on the same network?
- AP Isolation: Is router client isolation disabled?
- App version: Is Companion up to date?
- Project errors: Any red errors in the Rork editor?
- Cache: Have you reloaded/regenerated the project?
- Device memory: Have you closed background apps?
- Code issues: Any empty returns or infinite loops?
Working through this list methodically will resolve most cases. If you've checked everything and it still doesn't work, search Rork's official community or Discord — chances are someone else has hit the same issue and documented a fix.
For broader app generation issues, Rork App Not Building: Troubleshooting FAQ covers a wider range of common problems.
Advanced Debugging: Reading Companion Logs
When the checklist above doesn't point to an obvious fix, reading Companion's error output can tell you exactly what's failing.
On iOS, connect your iPhone to your Mac with a USB cable and open the Console app (found in /Applications/Utilities). Filter by your device and search for "Rork" or "RorkCompanion" to see live crash logs and JavaScript errors.
On Android, install ADB (Android Debug Bridge) and run:
# List connected devices
adb devices
# Stream logs filtered to Rork-related output
adb logcat | grep -i rork
# Or capture a full log to a file for review
adb logcat > companion_debug.logLook for lines tagged ReactNativeJS — these contain the JavaScript error messages from your app code, which are often more descriptive than what Companion shows on screen.
If you see errors like Unable to resolve module or Cannot find module, it usually means a package your project depends on isn't available in the Companion runtime. In that case, you may need to rebuild with EAS or check whether the package requires native code that Companion can't run.
What to Do When Nothing Works
If you've gone through every step and Companion still won't behave, here are your options:
Use Expo Go as a fallback. Rork projects are built on React Native and Expo, so Expo Go can serve as an alternative preview tool in some cases. It won't have the same tight integration as Companion, but it can help you verify whether the problem is specific to Companion or something broader with your code.
Try a different device or OS. Sometimes a problem that blocks one device doesn't appear on another. Testing on a secondary phone — or switching between iOS and Android — can help isolate whether the issue is device-specific.
Simplify your project. Start from a minimal template and gradually add back your code. If Companion works fine with a blank project, add your screens one by one until you find the component that breaks things.
Report to Rork support. Rork's team actively monitors their community channels. If you've hit a repeatable bug, reporting it with your device model, OS version, and steps to reproduce helps the team address it faster — and you might get a direct fix or workaround in the process.
Looking back
Most Rork Companion problems trace back to three things: your Wi-Fi environment, your Companion app version, and errors in your project code. Build a habit of checking these three first, and you'll spend far less time stuck.
For a deeper look at using Companion for real-device testing, visit Rork Companion iOS Real Device Testing Guide.