"I installed Rork Companion, scanned the QR, and it just spins forever." That was my own first day with Rork Companion. The web editor sat at "waiting for connection," the phone never finished loading. The causes range from trivial to subtle, but with the right diagnostic order you'll resolve it inside five minutes.
This guide organizes Rork Companion failures by symptom — connection, sync delay, broken preview — verified on both iOS and Android.
Step zero: are both devices on the same Wi-Fi?
After QR scan, Rork Companion needs to reach the web editor on the same network. Phone on cellular, PC on Wi-Fi means the QR login can succeed but the live preview never arrives.
Specifically check:
- The Wi-Fi SSID on phone matches the SSID on PC
- "Prefer cellular" is off on the phone
- VPN (especially corporate VPN) is off
I once burned an afternoon because my Mac was on the 5GHz band of the home Wi-Fi while my phone was on the same-named 2.4GHz band — same SSID name, different network segments. Some routers route them as separate networks.
Common QR login failures
A: Stale QR code
Rork's QR codes expire after roughly 60 seconds. Leave the screen long enough and even a successful scan returns "QR has expired." Refresh the page to generate a new one.
B: Outdated Companion app
The App Store / Google Play versions update often. An outdated Companion may not understand newer QR formats. Update the app.
C: Camera permission not granted
If scanning won't work at all, camera permission is the usual cause. Check Rork Companion's permission in Settings → Rork Companion → Camera (iOS) or App Info → Permissions → Camera (Android).
QR connects, but preview doesn't refresh
Different problem. You're connected, you edit code, the phone shows the old build. Possible causes:
Cause 1: hot reload signals can't get through
Rork's preview runs hot reload over WebSocket. Several things can interrupt it:
- The phone went to sleep — wake it and bring Companion to the foreground
- Companion was backgrounded — reopen it
- Battery optimization is restricting Companion in the background — frequent on Android
For Android battery optimization:
Settings → Apps → Rork Companion → Battery → Unrestricted (or Don't Optimize)
Cause 2: the file isn't actually saved
Without Cmd+S in the web editor, the file is "modified" but not saved on Rork's server. Check the save indicator in the editor's top right ("Saving..." → "Saved").
Cause 3: you edited a native module config
Changes to Expo native module configuration (app.json, expo-build-properties) don't reload via hot reload. Tap "Rebuild Preview" in Companion, or run "Force Rebuild" from the web editor.
"Connection Failed" with no obvious cause
A red "Connection Failed" appears in Companion despite all of the above being clean. Two common causes in my experience:
1. Rork server-side issue
If Rork has an official status page, check it first. If the platform is degraded, you wait. Searching X for "rork down" sometimes surfaces other people reporting the same.
2. Project-specific dependency error
A package.json referencing a nonexistent package, or one incompatible with your Expo SDK, can prevent the build from completing — and Companion never establishes a connection. Check the build log (terminal panel, lower left in the web editor).
A frequent culprit: AI-generated code containing hallucinated package names. react-native-amazing-feature — looks plausible, doesn't exist. I've seen this enough times to make it a default first check.
Native features that don't work in Companion
Some native features are intentionally limited in the Companion preview:
- Camera, microphone, and location permission dialogs appear in the Companion app, not in your previewed app
- Push notifications don't deliver through Companion (you need a real build)
- App Clips and Widgets can't be reproduced in Companion
To test these, build with EAS Build and distribute via TestFlight or Internal Testing.
Diagnostic checklist
Walk through these in order based on the symptom.
Can't log in via QR
- Same Wi-Fi on phone and PC?
- QR scanned within 60 seconds?
- Companion app on the latest version?
- Camera permission granted?
Logged in but preview is stale
- Companion in the foreground?
- Cmd+S in the web editor?
- If you edited native modules, did you Rebuild Preview?
- On Android, is battery optimization disabled for Companion?
"Connection Failed" appears
- Rork server status?
- Any errors in the web editor's build log?
- Anything wrong in
package.jsondependencies?
What to do first
Whenever you hit a connection issue, just check "same Wi-Fi" first. That alone resolves about 60% of cases. If it doesn't, walk down the symptom-specific checklist.
Because Rork builds happen in the cloud, telling "your environment" from "the platform" is harder than in local dev. Get used to reading the web editor's terminal output — that's where the actual error usually shows up.