Troubleshooting

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

The dev server stops before it starts

Frontfriend: The design system is not installed in this project yet. means init has not run in this project. Sign in with pnpm exec frontfriend login if you have not yet, run pnpm exec frontfriend init, then start the app again.

Components render without styles

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

pnpm exec frontfriend status
pnpm exec frontfriend init --force

Inspect cache generation errors and restart the dev server if necessary. Use the CSS-first integration in Installation; regenerate cached CSS through the CLI.

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.

• No Design System connected to this project: the project has no ff-id. Create or open a Design System, then run pnpm exec frontfriend setup --ff-id YOUR_DESIGN_SYSTEM_ID. The CLI did not change the project.
• Design System "…" was not found: the ff-id does not match a Design System. Copy it again from Frontfriend.
• You don't have access to this design system yet: your account is not a member of the Design System’s workspace. Ask a workspace admin to invite your sign-in email, accept the invitation from the email, then run pnpm exec frontfriend init again. If you signed in with another account, switch with pnpm exec frontfriend login.
• Frontfriend denied this operation on Design System "…": your account can access the Design System, but your workspace role or plan does not allow the command. Ask a workspace admin.

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 pnpm exec frontfriend download COMPONENT --dry-run with workspace access and the correct Release and target. Sign in with an account that has access to the Design System and install through the Frontfriend CLI.

A token change does not appear

Check whether the change was published, which Release the selected tag points to, and which token Release the local lock pins. init --force refreshes the pinned selection; it does not adopt a newer Release. Preview pnpm exec frontfriend adopt --dry-run, review it, then apply with --yes and verify the app. Historical releases remain immutable.

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. Keep credentials and private Design System exports out of public reports.