Last updated on September 14, 2026
Troubleshooting
Check versions and restart
RC0 requires nativewind@5.0.0-rc.0 and react-native-css@3.1.0-rc.0 together. Check the resolved versions in your lockfile or with npm ls nativewind react-native-css. Use the equivalent command for your package manager.
After changing dependencies or configuration, restart Metro:
Rebuild native apps when native dependencies change. The tested target is Expo 57.0.22 with React Native 0.86.3, Reanimated 4.5.1 and Worklets 0.10.1. Align native packages with Expo rather than bypassing peer errors.
Build succeeds but styles are missing
V5 compiles Tailwind 4 through @tailwindcss/postcss. Expo 57 discovers postcss.config.js or postcss.config.mjs, but not postcss.config.cjs. Check the installation guide, root CSS import and Tailwind source discovery.
For an isolated Tailwind check using the same tested version:
Check that the expected utility exists in the output. This verifies Tailwind generation only; it does not verify Metro integration or native rendering.
On web, use the split theme, preflight and unlayered utility imports from the installation guide. A single @import "tailwindcss" can let React Native Web default styles win over your utilities.
Legacy configuration errors
The RC rejects @cssInterop, @react-native configuration and qualified native root selectors such as :root.dark. Follow Upgrade a v5 preview to translate their intent. Do not suppress these errors.
verifyInstallation, cssInterop and remapProps are not Nativewind RC0 exports. Use styled for component mapping and verify a visible styled element instead of calling the v4 installation helper.
Runtime variables do not update
Use VariableContextProvider with its value prop. Preserve dynamic variables with inlineVariables.exclude in Metro options. See Dynamic Themes.
Theme changes do not apply
Install expo-system-ui, set expo.userInterfaceStyle to "automatic", and rebuild for native configuration changes. On the tested Expo 57 target, Appearance.setColorScheme("unspecified") restores system appearance. Browser manual theme controls need separate configuration. See Dark Mode.
Unsupported component props
Adding a TypeScript declaration does not create a runtime mapping. Use supported native props or a styled wrapper for third party components. For TextInput placeholder color, use className="placeholder:text-gray-500".
Platform differences and bug reports
Apply text colors to Text components rather than expecting them to cascade through View. Native px values become density independent points, and the default native rem is 14. Compare intended layouts on each supported platform.
Check the RC compatibility guide, including the Android animation cancellation limitation. When reporting an issue, include exact package versions, Expo SDK, platform and OS, development or release mode, configuration, expected and actual behavior, and a minimal reproduction. Note whether direct React Native or Reanimated reproduces it.