Rork App Won't Build? Eight Symptoms to Sort Out First

Every solo developer has the night when the build simply won't pass. I search the error, try every fix the results suggest, and somewhere along the way break a second thing. I did exactly that for a long time.

Looking back, the problem was rarely a missing command. It was that I never asked which layer the failure lived in: packages, my dev environment, Rork's generation, or the code itself. Once the layer is clear, the fix usually narrows to one or two commands.

This FAQ is organized by layer. You don't need to read it top to bottom. Open the question that matches what you're seeing.

Q1: "Build failed." What is a dependency conflict?

A: The most common cause is two packages demanding incompatible versions of a third. Package A wants library X 1.x, package B wants 2.x. If your log mentions conflicting peer dependency or ERESOLVE, this is almost certainly it.

# Rebuild dependencies from scratch
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

If npm install still stops, --legacy-peer-deps relaxes the strict peer check:

npm install --legacy-peer-deps

:::warning This flag doesn't resolve the conflict; it chooses not to look at it. After it passes, confirm the app actually launches. If it doesn't, go back and align the version of the package named in the log. :::

For packages tied to your Expo SDK (expo-* and some react-native-* packages), this is safer than a plain install:

npx expo install --fix

Q2: "Unable to resolve module" for an Expo package

A: Either the dependency isn't installed or Metro's cache is stale.

npm ci
npx expo start --clear

Some older guides recommend npm install -g expo-cli. A global expo-cli is no longer the way to go; use npx expo ... inside the project. A stale global copy can drift from your project's SDK version and add confusion.

npx expo --version   # should print the version installed in your project

One distinction worth keeping: npm ci reproduces exactly what the lock file says, while npm install tidies up from whatever state you're in. When you want a clean reproduction, use ci.

Q3: The iOS simulator won't start

A: This is a dev-environment problem; your code is almost never involved. Check three things in order.

Xcode and command-line tools (macOS only):

xcode-select --install
xcode-select -p   # a printed path means it's set

The simulator itself:

xcrun simctl list devices available
xcrun simctl boot "iPhone 16 Pro"   # use a name from the list

Port 8081 already in use:

lsof -i :8081
npx expo start -p 8082

:::tip When the simulator refuses to cooperate, test on a real phone with Expo Go. It sidesteps simulator-specific trouble and tells you quickly whether the app itself is at fault. :::

Q4: The Android emulator shows only a white screen

A: A white screen means nothing could be drawn. The cause is usually one of four things: an unfinished bundle, the JDK, the emulator's resources, or the connection.

Start by clearing Metro's cache:

npx expo start --clear

Confirm the terminal shows bundling progress, then press r in the emulator. If there's no progress in the terminal, the cause is on the terminal side, not in the emulator.

Next, check your JDK:

java -version

The recommended JDK changes between Expo SDK versions, so I won't hard-code a number here. Check the requirements in the official docs for your SDK.

If memory is tight, open Device Manager in Android Studio, edit the device, and raise its RAM. If that doesn't help, try a Cold Boot, which starts without the saved snapshot.

:::warning Staring at a white screen won't give you an answer. The answer is usually in the red lines in your terminal. :::

Q5: The prompt won't generate an app / generation freezes

A: This layer is Rork's side plus your network. There are three things to try before touching any code.

First, shrink the prompt. Cramming in every feature makes generation drag until it looks frozen. Generate the core, then add features afterward.

// Too much at once
"A chat app with real-time notifications, profile photos, search,
groups, voice messages, video calls, blocking, read receipts..."

// Start small
"A chat app where users can send and receive messages.
A simple UI is fine."

Second, check your connection. An unstable Wi-Fi link stalls generation midway; switch networks and retry.

Third, give the browser room. Many open tabs slow it down. Close the extras, and try another browser if it persists.

Q6: Images or icons don't appear

A: Mostly a path mistake or a package-name mix-up.

One wrong level in a relative path is enough to make an image vanish:

// Recount the path relative to the file's location
<Image source={require('../../assets/images/my-image.png')} />

For icons, the standard package is @expo/vector-icons, and the name is easy to confuse:

npx expo install @expo/vector-icons

Spaces or non-ASCII characters in file names can fail to resolve on some setups, so keep them to letters, digits, hyphens, and underscores. If the display is stale, clear the cache with npx expo start -c.

Q7: Hot reload doesn't work

A: Current Expo enables Fast Refresh by default, so flags like --hot aren't needed. Check these in order:

1. Is the file saved? Look for an unsaved marker on the editor tab.
2. Is there a syntax error? A red error screen blocks updates until it's fixed.
3. Is the connection alive? Your device and development machine need to be on the same network.
4. Reload from the developer menu. Cmd + D on the iOS simulator, Cmd + M (Ctrl + M on Windows) on the Android emulator.

If nothing helps, stop Metro and restart with npx expo start --clear.

:::tip A one-to-two-second delay isn't a bug. React in development can render twice on purpose to catch mistakes; production builds don't. :::

Q8: Is the "Fix Now" button safe to use?

A: Yes, if you pick your moments. When Rork hits a build or runtime error, it can show a Fix Now button under the message. It sends the error and surrounding code to the AI and applies a proposed fix.

It's good when the cause is spelled out in the message: an unclosed bracket, a forgotten import, a function name that doesn't exist, a type mismatch. One press often solves these.

It's weak when the cause lives outside the code: dependency conflicts (Q1), simulator or emulator trouble (Q3, Q4), a frozen generation (Q5). These aren't "fix the code" problems, so Fix Now can apply a fix that misses the point.

This is the order I follow:

1. Read the message myself once
2. If it's a syntax or import error, press Fix Now
3. Always read the diff that was applied
4. If the same Fix Now fails twice in a row, stop and go back to the layer check in Q1–Q7

Never keep pressing it without reading what changed—that's the line I hold, because the AI can rewrite unrelated places and leave things more tangled than before.

Your next step

When a build error shows up, read the message to the end and decide which layer it belongs to: packages, dev environment, Rork's side, or code. Then try only that layer's question.

If a build is failing on you tonight, copy the first red line from your terminal and compare it with the table above.