Troubleshooting

Find the symptom below, then check each likely cause in order.

The badge doesn’t appear

Likely cause	What to do
It’s a Vite, Remix, Astro or WXT preview	These previews don’t show the badge on arrival. Add `?skyelight=1` to the address. Links from Skyelight include it.
Your Content-Security-Policy blocks it	Add the sources in Privacy and CSP. The browser console names the blocked request.
You have the Chrome extension installed	The badge removes itself when the extension is present. Use the extension, or open the page in a browser profile without it.
It’s a production build	With `production: false`, production builds get no badge. Open a preview instead.
The badge is turned off	Check `widget` in your config. In a config without `production`, check `SKYELIGHT_WIDGET`.
The page was built before setup	View the page source and look for a script tag that loads `a.js`. If it’s missing, deploy again after setup.

Likely cause	What to do
The address isn’t on the project’s list	A project owner or admin adds it under Project settings Review Links. See Preview URLs.
The address doesn’t match exactly	The scheme, host and port must match the entry. Wildcards aren’t accepted, so add each preview address separately.
The address uses `http`	Addresses must use `https`. Only `localhost`, `127.0.0.1` and `*.localhost` can use `http`.
The same address is on two projects	Set `project` in the plugin options to the right project ID.
The reviewer isn’t in the workspace	Invite them to the workspace. The badge signs in workspace members only.
The browser has an old session	Add `?skyelight=0` to the address to sign that browser out of the badge, then try again.
Vercel’s login page appears first	Add your Vercel bypass secret to the project. See Deployment bypass.

Pins arrive without a source location

Likely cause	What to do
The build has no stamps	With `production: false`, production builds have no stamps. Check `stamp`, or `SKYELIGHT_STAMP` in a config without `production`.
Page context is off for the workspace	Stamps are saved in a thread’s page context. A workspace owner or admin can turn page context back on in the workspace settings.
The element is a component or a member expression	`<PricingCard />` and `<motion.div />` get no stamps. Pin an element rendered inside them.
The file isn’t `.jsx` or `.tsx`, or is a dependency	The plugin stamps only `.jsx` and `.tsx` files outside `node_modules`.

To check a page, inspect an element in your browser’s developer tools and look for a data-sky-src attribute.

The commit is wrong in local development

The commit on <html> comes from your root layout, which your bundler caches. Restart the dev server, or save the layout file, to update it. The file and line stamps on elements are not affected.

”Unknown command: verify”

The @skyelight/build installed in your project is older than 0.14.0, the version that added verify. npx runs the installed copy, not the latest version. Update it, then run verify again:

npm install -D @skyelight/build@latest

`verify` fails in CI

npx @skyelight/build verify prints Found Skyelight in this build: and lists each file with the attribute or script it found.

Check that your config sets production: false.
Check that the plugin detects the build as production. On CI other than Vercel and Netlify, set SKYELIGHT_ENV=production for production builds, or make sure NODE_ENV=production is set.
Check that verify reads the production output, and not a preview build left in the same directory.

If verify prints No build output found, run your build first, or pass the output directory, such as npx @skyelight/build verify dist.

TypeScript rejects an option

Check the option’s spelling against the options table, and where it applies: autoStart is Next.js only, and root is Vite only. Type declarations for every option ship with 0.14.0 and later. To update an older copy, run setup again or run npm install -D @skyelight/build@latest.

If none of these fixes the problem, email support@skyelight.ai with your framework, the plugin version and the preview address.