Troubleshooting

“Invalid license key” error

• Double-check that your .env.local file is in the project root
• Verify the license key is copied correctly without extra spaces
• Make sure you’re using the correct variable name: STARWIND_LICENSE_KEY

Blocks not installing

• Ensure you ran starwind@latest init --pro first
• Check that your license key is valid and active
• Make sure you run the install command from your project root

Page scroll stays locked after a selection

This can happen in astro dev with a Select-based control, such as Theme Switcher 5. Vite can load two copies of the Starwind Runtime. One copy comes from its dependency cache and one comes from the package files. Each copy then attaches its own controller to the same Select. Both controllers lock page scroll when the popup opens. When the popup closes, one controller can put the lock back on the page.

Tell Vite to load the Starwind packages from one source. Add this to astro.config.mjs:

1
export default defineConfig({
2
  vite: {
3
    optimizeDeps: {
4
      exclude: ["@starwind-ui/astro", "@starwind-ui/runtime"],
5
    },
6
  },
7
});

Restart the dev server after you change the config.

Need more help?

• Check the Installation Guide for setup instructions
• Join the community for support and updates