On a Saturday morning I opened the reviews for one of my apps and found a one-star review that said only: "Doesn't get past the start screen." No device, no date, nothing else. I sat with the cursor in the reply box for a while, not sure what to say.
As an indie developer who has kept a few apps running for years, I get a line like this every so often. Early on I'd reply quickly with "Please try reinstalling." It didn't go well. I never learned whether it helped, and a week later the same symptom showed up again in another language.
The thing I'd like to say first: "stuck on the splash screen" mixes two kinds of problems. Some can be handled with a reply. Others need a fix in your next release. Checking three clues before replying is how I tell them apart.
Why an app stays on the splash screen
An app built with Rork (React Native and Expo under the hood) shows a splash screen at launch and hides it once the app is ready. The signal to hide it comes from the app's own code.
So "stuck on the splash screen" means that signal never fired. There are roughly three reasons:
- The app crashes while loading and keeps relaunching
- The app loads, but something it waits on before hiding the splash never finishes
- An update you shipped with EAS Update didn't fit, the app fell back to an earlier version, and got stuck there
On that third one, there is an open report on Expo's GitHub of apps staying on the splash screen after error recovery rolls back to a previous update; as of November 21 it is unresolved (expo/expo#53933). Expo's error recovery relaunches the app from an earlier update, or from the version embedded in the binary, when a new update fails to launch (Error recovery). It's there to protect users, but if the fallback stalls, all the user sees is the splash screen.
Clue 1: which update is the app running?
The first thing I want to know is what code the app is actually running. But someone stuck on the splash screen can't show you anything inside the app. So I now keep a single line at the bottom of the settings screen that shows the running update.
// components/BuildInfoLine.tsx
// One line at the bottom of Settings, so support can ask "what does this line say?"
import * as Updates from 'expo-updates';
import { Text } from 'react-native';
export function BuildInfoLine() {
// In development (Expo Go or a dev build) updateId is null
const id = Updates.updateId ? Updates.updateId.slice(0, 8) : 'embedded';
const source = Updates.isEmergencyLaunch
? 'emergency' // loading the update failed; launched the embedded version
: Updates.isEmbeddedLaunch
? 'embedded' // launched the version bundled in the binary
: 'ota'; // launched an update you shipped
return (
<Text style={{ fontSize: 11, opacity: 0.5, textAlign: 'center' }}>
{`${Updates.runtimeVersion ?? '-'} / ${Updates.channel ?? '-'} / ${id} / ${source}`}
</Text>
);
}isEmergencyLaunch is true when the shipped update failed to load and the app fell back to the embedded version. If several people report emergency, this isn't something a reply will fix. Look at the update you shipped last.
The person who is stuck right now can't see this line, of course. It helps most with people who could open the app before and then couldn't, or when someone else in the household can check on the same device. It's half a clue, but it's far better than none.
Clue 2: what did you ship just before?
The second clue is your own record. Put the review dates next to the dates you shipped something:
- The day a new store build went live after review
- The day you pushed an EAS Update (including publishing from Rork)
- The day you raised a staged rollout percentage
If the reports cluster right after one of those, that release is the first suspect. If they arrive during a quiet stretch, I'd look at the user's side first: free storage, network, an OS update.
I got this wrong once. I pulled my latest update as soon as I read a report, and the real cause turned out to be a phone that was out of storage. That update also carried an unrelated fix, so I rolled that back too. Line up the dates before you pull anything. I try not to skip that even on a rushed morning.
How long to wait before raising a staged rollout is covered in how many sessions to wait for in the first 5%.
Clue 3: is the code that hides the splash waiting forever?
The third clue is in the code. Even code Rork wrote may wait on fonts, a sign-in check or remote settings before hiding the splash screen. If one of those never returns, the splash never goes away. When only people on weak connections get stuck, this is usually why.
The fix is to put a ceiling on the wait.
// Part of app/_layout.tsx
// Hide the splash after 8 seconds even if preparation hasn't finished
import * as SplashScreen from 'expo-splash-screen';
import { useEffect, useState } from 'react';
SplashScreen.preventAutoHideAsync();
const SPLASH_LIMIT_MS = 8000;
export function useAppReady(prepare: () => Promise<void>) {
const [ready, setReady] = useState(false);
useEffect(() => {
let done = false;
const finish = () => {
if (done) return;
done = true;
setReady(true);
SplashScreen.hideAsync().catch(() => {}); // hiding twice must not crash
};
const timer = setTimeout(finish, SPLASH_LIMIT_MS);
prepare()
.catch((e) => console.warn('prepare failed', e)) // move on even if it fails
.finally(() => {
clearTimeout(timer);
finish();
});
return () => clearTimeout(timer);
}, []);
return ready;
}Why move on even after a failure? Because a screen with something missing still lets the user decide what to do next, while a frozen splash screen doesn't. If settings can't be fetched, open with defaults; if the sign-in check never answers, show the sign-in screen. Eight seconds is my own rule of thumb; pick what fits your app.
When I ask Rork to fix this, I start with: "List everything the app waits on before hiding the splash screen, and make it move on after 8 seconds." Having it name what it waits on first makes the rest go faster. Sending logs along with the request works the same way as in asking for logs before asking for a fix.
How I split the replies
Once I've checked the three clues, I write the reply. This is how I split them:
| What I found | What the reply says | What I do on my side |
|---|---|---|
| Reports line up with a recent release | That I'm aware of the bug and plan to fix it in the next update | Consider pulling the release and check clue 3 |
| No recent release, a single report | Free up some storage and restart the app once | Watch for a few days to see if it repeats |
| Happens on weak connections | Try opening once on a stable connection | Add a ceiling to the wait |
I no longer lead with "Please try reinstalling." Reinstalling can wipe data stored on the device, and if it doesn't help, the user has lost more than they gained.
A different symptom, where an Android crash leaves a blank white screen and people describe the app as "frozen," is covered in when a crash gets reported as "frozen". If the report says white screen rather than splash screen, start there.
One thing to do today
Put that single line about the running update at the bottom of your settings screen, and ship it in your next release. The person who's stuck can't see it, but it gives you something to work with the next time a one-line review arrives. Since I added it, I've had fewer of those mornings where opening the reviews makes my stomach tighten.