# Troubleshooting
URL: /docs/guide/troubleshooting

Common issues and solutions when using Docyrus UI.

## Verify your versions

Make sure your environment meets or exceeds these minimum versions to ensure Docyrus UI components work correctly.

### Web

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| Next.js | 16 |
| Tailwind CSS | 4.0 |
| Node.js | 18 |
| Radix UI | 1.4.0 |

### React Native

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| React Native | 0.83 |
| Expo SDK | 55 |
| Uniwind | 0.1+ |
| Node.js | 18 |

## Web

### Registry not found

If you see a "registry not found" error when installing components, make sure you've added the Docyrus registry to your `components.json` file. The registry URL should point to `https://ui.docy.app/r`. Without this entry, neither the shadcn CLI nor the Docyrus CLI will know where to fetch components from.

### Components not resolving after installation

After installing a component, your imports should point to the local file path where the component was placed — not to an NPM package. If your IDE shows unresolved imports, check that the component files were actually written to disk and that your TypeScript path aliases match the install location.

### Tailwind CSS v4 classes not applying

Tailwind CSS v4 uses a CSS-based configuration system. If component styles aren't applying, make sure your CSS entry file includes a `@source` directive that covers the directory where Docyrus UI components are installed. Without this, Tailwind's compiler won't scan those files for utility classes.

### Dark mode not working

Docyrus UI components use CSS custom properties (CSS variables) for theming. Dark mode relies on these variables being defined in your global stylesheet. If dark mode isn't working, verify that your theme variables are set up correctly for both light and dark color schemes.

### Motion library version conflicts

Some Docyrus UI components use the Motion library for animations. If you see runtime errors related to motion or framer-motion, make sure you're using a compatible version. Docyrus UI targets Motion v12 and above.

## React Native

### 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`.

### Expo Go compatibility

Some native components require a development build and won't work in Expo Go. Check the component's `expoGoCompatible` flag in the documentation. Components that use native modules (e.g., `expo-document-picker`, `expo-localization`) require `npx expo prebuild` and a custom dev client.

### 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 peer dependency:

```bash
npx expo install react-native-svg
```

### 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.

## 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.