# Troubleshooting
URL: /docs/native/guide/troubleshooting

Common issues and solutions when using Docyrus UI native components.

## Verify your versions

Make sure your environment meets or exceeds these minimum versions.

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| React Native | 0.79 |
| Expo SDK | 53 |
| Node.js | 18 |

## Components look transparent or unstyled

Surfaces, borders and text colors come from the Docyrus design tokens (`bg-background`, `border-field-border`, `bg-sheet-surface`, …). If they render transparent, your Uniwind CSS entry is missing the tokens import — add it after Tailwind and Uniwind, with a path relative to that file:

```css title="src/styles/global.css"
@import "tailwindcss";
@import "uniwind";
@import "./docyrus-native/index.css";
```

The file is installed by the CLI with any `rn-*` component (`docyrus add rn-styles` installs it alone). Restart Metro with `npx expo start --clear` after changing the CSS entry. `Theme X is missing variable …` means a token you override is declared in one `@variant` but not the other; `Cannot use @variant with unknown variant` means `color-schemes.css` is imported without its themes in Metro `extraThemes` (or through a package path instead of a relative one) — see [Theming](/docs/native/guide/theming#color-schemes).

## Theme not applying

Make sure your app is wrapped with `DocyThemeProvider` at the root level. Without this provider, components will fall back to default styles. If using Expo Router, wrap it in your root `_layout.tsx`.

```tsx title="app/_layout.tsx"
import { DocyThemeProvider } from '@/lib/docyrus/theme';

export default function RootLayout() {
  return (
    
  );
}
```

## Expo Go compatibility

Some native components require a development build and won't work in Expo Go. Check the component's documentation for Expo Go compatibility. Components that use native modules require `npx expo prebuild` and a custom dev client:

```bash
npx expo prebuild
npx expo run:ios
```

## Missing peer dependencies

Native components declare peer dependencies for packages like `react-native-svg`, `expo-document-picker`, and `expo-localization`. If you see module resolution errors, install the required dependency:

```bash
npx expo install react-native-svg
npx expo install expo-document-picker
npx expo install expo-localization
```

## Font Awesome icons not loading

If `DocyrusIcon` is not rendering icons, make sure you've configured the icon CDN path correctly. Native icons are loaded from the Docyrus CDN — verify your network connectivity and that the icon name matches the registry.

## React Native Reanimated errors

If you see errors related to Reanimated, make sure you've added the Babel plugin:

```js title="babel.config.js"
module.exports = function(api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-reanimated/plugin'],
  };
};
```

## Metro bundler cache issues

If you're seeing stale code or unexpected errors after installing new components, clear the Metro cache:

```bash
npx expo start --clear
```

## Still having issues?

If none of the above solutions resolve your problem, please [open an issue on GitHub](https://github.com/docyrus/docyrus-ui/issues) with a description of what you're experiencing and your environment details.