# Troubleshooting

Find the broken connection and get back to building.

Start with the exact installed package version and the failing command. Compare your application target, config and CSS imports before replacing component source.

## Components render without styles

Check that Tailwind CSS v4 is configured and imported before `@frontfriend/tailwind/theme.css`. Verify the Frontfriend Vite plugin or Next.js wrapper, then run:

```bash
npx frontfriend status
npx frontfriend init --force
```

Inspect cache generation errors and restart the dev server if necessary. Do not paste a Tailwind v3 plugin into a v4 build or hand-edit cache CSS as a permanent fix.

## The CLI cannot find the Design System

Run from the application root. Check that `frontfriend.config.js` exports the intended `ff-id` and uses the right module format. Confirm workspace access and complete `frontfriend login` if the operation requires authentication.

## A downloaded component will not compile

Confirm React/Vue compatibility and the selected primitive. Install dependencies reported by the downloader. Verify the `@/components/ui` alias and any Icon or Spinner dependencies. An error about `asChild`, `render` or `onPress` often indicates an example from the wrong target.

## A component is missing from the registry

Use a canonical route including framework and primitive. Check the package and registry versions; do not silently fall back to legacy source.

## A token change does not appear

Check which source owns the property, whether the Design System version was saved and which version your application consumes. Refresh token cache and inspect the generated utilities. Overlapping Studio and configuration edits may need review while canonical authoring improvements are still in progress.

## An overlay behaves incorrectly

Check the exact primitive’s composition. Preserve native trigger and dialog wrappers, accessible title and focus behavior. Test outside press and Escape, including when the overlay is nested.

## Ask for help

Share the package version, framework/primitive, sanitized config, minimal reproduction and exact error with [the Frontfriend team](https://www.donux.com/contact-us). Keep credentials and private Design System exports out of public reports.