Troubleshooting

Verify your versions

Make sure your environment meets or exceeds these versions to ensure Sora UI remains compatible and stable.

Documentation display issues

Certain browser extensions can interfere with how the documentation is rendered. Common culprits include:

• Screen Shader | Smart Screen Tinting

If problems persist after disabling extensions, clear your browser cache and refresh the page.

The CLI does not recognize @soralabs

Sora UI is listed in the official shadcn registry index. Register the namespace first:

npx shadcn@latest registry add @soralabs

If that still fails, add or update the registries field in components.json:

{
  "registries": {
    "@soralabs": "https://ui.soralabs.studio/r/{name}.json"
  }
}

If you were testing against a local docs server (http://localhost:3000/r/{name}.json), switch back to the production URL when:

• The dev server is not running
• shadcn list or shadcn add times out or returns 404
• You are installing into a project outside this monorepo

Verify the registry is reachable:

bunx --bun shadcn@latest list https://ui.soralabs.studio/r/registry.json

Then install with the scope, for example:

bunx --bun shadcn@latest add @soralabs/accordion

A Sora dependency resolves from ui.shadcn.com

If shadcn add @soralabs/accordion fails with a 404 for something like hooks-use-auto-height on ui.shadcn.com, the published registry item listed that dependency without the @soralabs/ scope. Sora-only deps must be scoped so the CLI fetches them from your @soralabs registry URL, not the default shadcn registry.

Ensure components.json includes the Sora registry (see above), then retry after the registry on https://ui.soralabs.studio/r/ is updated. For local testing, point @soralabs at http://localhost:3000/r/{name}.json while bun dev is running in this repo.

The CLI installation does not respect aliases

In some projects, components may not install in the desired location that you configured in the aliases in the components.json file. This is because we can't use a target path with aliases.

We have filed an issue on shadcn/ui, Shadcn added it to the roadmap.

For now, we recommend using the manual installation.

Flickering with the highlight component

If you are experiencing flickering issues with the Highlight component, this is likely due to React's strict mode. Set it to false to avoid issues during development.

Other issues

If you encounter any other problem, see the Community page — open an issue or ask in Discussions.