Expo app never leaves the splash screen
App shows the splash screen forever and no error appearsShort answer
After SplashScreen.preventAutoHideAsync() the splash stays until you hide it yourself. The app stays stuck when hide is never called, or when the ready flag is only set after async work succeeds and that work throws or never finishes. Hide it from a flag set in a finally block.
Fix it fast
1Find out which cause you have
Search the project for every call to the splash screen module and see where preventAutoHideAsync and hide are used.
grep -rn "SplashScreen\." app src App.* --include=*.tsx --include=*.js2Match what you see, then jump to its fix
- 1
The grep shows preventAutoHideAsync and no hideAsync or hidepreventAutoHideAsync is called but hide is never reachedFix - 2
A fetch, font load or storage read runs before setIsReady(true)The ready flag is set only when async startup work succeedsFix - 3
The splash looks different or sticks only in developmentThe check was made in Expo Go or a dev buildFix
- 1
What does the error look like?
App shows the splash screen forever and no error appears
Cause 1 of 3
preventAutoHideAsync is called but hide is never reached
1Check
preventAutoHideAsync keeps the splash visible until hideAsync is called.
grep -rn "hideAsync\|SplashScreen.hide" app src App.* --include=*.tsx --include=*.js2Fix
Call preventAutoHideAsync at global scope, outside any component, and hide the splash from an effect once the app is ready.
SplashScreen.preventAutoHideAsync();
useEffect(() => {
if (isReady) {
SplashScreen.hideAsync();
}
}, [isReady]);3Verify
Restart the app. The splash disappears when isReady becomes true.
npx expo start --clearConfirmed by docs.expo.dev
Cause 2 of 3
The ready flag is set only when async startup work succeeds
1Check
If that work throws or hangs, isReady stays false and the splash never hides.
grep -rn "setIsReady\|setReady\|setAppIsReady" app src App.* --include=*.tsx --include=*.js2Fix
Set the flag in a finally block so a failure still ends the splash, and log the error.
useEffect(() => {
async function prepare() {
try {
// load fonts, read storage
} catch (e) {
console.warn(e);
} finally {
setIsReady(true);
}
}
prepare();
}, []);3Verify
Break the async step on purpose (go offline). The app should still leave the splash.
npx expo start --clearConfirmed by docs.expo.dev
Cause 3 of 3
The check was made in Expo Go or a dev build
1Check
Expo notes that Expo Go and development builds do not fully reproduce the splash screen.
npx expo --version2Fix
Test the behaviour on a release build before changing code.
npx expo run:ios --configuration Release3Verify
The release build leaves the splash when the app is ready.
npx expo run:ios --configuration ReleaseConfirmed by docs.expo.dev
How do I stop it coming back?
- Call preventAutoHideAsync at the top of the file, not inside components or hooks.
- Always set the ready flag in finally.
- Hide the splash as soon as content is ready, to avoid a blank screen.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView
Error: NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized.
react-native-gesture-handler only recognises gestures inside GestureHandlerRootView.
3 causes, each with a fixWeb apps
React Hook "useState" cannot be called at the top level, or in a function that is not a component
The lint points at a useState line inside a helper function, an onClick handler or the top of a module
The lint rule found a hook outside a component or custom hook.
3 causes, each with a fixWeb apps
React: Maximum update depth exceeded or Too many re-renders
Maximum update depth exceeded
React stops a component that sets state again and again without end.
3 causes, each with a fixWeb apps
React Native says the application has not been registered
Application has not been registered
The native side asks JavaScript to run an app name that JavaScript never registered.
3 causes, each with a fixWeb apps
TypeScript marks className as an error on React Native components
Property 'className' does not exist on type
React Native components have no className prop in their own types.
3 causes, each with a fix