Skip to main content

Troubleshooting

Common issues when developing with LightningAddon and how to resolve them.

Environment Validation Errors​

Symptom: Extension fails to load or background script errors with a list of missing keys.

Cause: parseIntegrationEnv() in @repo/integrations validates env at background startup. If you provide any key for an integration, all required keys for that integration must be present.

Fix:

  • Check envs/.env.development (or .env.production) for extension apps
  • Supabase: need VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY
  • Firebase: need VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID
  • Stripe: at minimum VITE_STRIPE_PUBLISHABLE_KEY
  • See Environment Setup for the full list

Manifest Permission Policy Failed​

Symptom: pnpm lint or pnpm build fails with "Manifest permission policy failed" and messages like "move 'tabs' from permissions to optional_permissions".

Cause: repo-manifest-lint enforces Chrome Web Store policy: privileged permissions (tabs, cookies, history, webRequest) must be in optional_permissions, not permissions.

Fix:

  1. Open apps/extension/manifests/manifest.chrome.json (or firefox)
  2. Move the listed permission from permissions to optional_permissions
  3. Add chrome.permissions.request() at runtime when you need the permission (before using tabs, cookies, etc.)

See Manifest Permissions for details.

Extension Won't Load (Chrome)​

Symptom: "Load unpacked" fails or extension shows errors in chrome://extensions.

Checks:

  1. Build first: Run pnpm build:chrome and select apps/extension/dist
  2. Fresh profile: Test on a clean Chrome profile to rule out conflicts
  3. Console: Open the service worker or popup context and check for errors
  4. Manifest: Ensure manifest.json exists in the dist folder and is valid

Billing / Checkout Fails​

Symptom: "Upgrade to Pro" or "Manage subscription" returns an error or doesn't open Stripe.

Checks:

  1. Backend running: Supabase Edge Functions or Firebase Cloud Functions must be deployed or running locally
  2. Stripe keys: STRIPE_API_KEY, STRIPE_WEBHOOK_SIGNING_SECRET, and price IDs set in backend env
  3. Auth: User must be logged in; the backend validates the auth token
  4. CORS: Billing flows through the background service worker (not popup/content script), so CORS should not be an issue—but verify the backend URL is correct

Storage Migrations Not Running​

Symptom: Old data format causes errors after an update, or new fields are missing.

Cause: Migrations are defined in apps/background/src/index.ts as STORAGE_MIGRATIONS. The background runs them on startup. If the background hasn't restarted, migrations won't run.

Fix:

  • Reload the extension from chrome://extensions (or restart the browser)
  • Ensure migrations are numbered correctly and run in order
  • See Storage Migrations

Auth Not Persisting (Supabase)​

Symptom: User has to log in again after closing the browser.

Cause: Supabase uses cookie-based session restore. The extension reads sb-access-token and sb-refresh-token from chrome.cookies. If the domain is wrong or cookies are blocked, restore fails.

Fix:

  • Ensure Supabase URL and anon key match your project
  • Check that the extension has cookies permission (can be optional) if using cookie-based restore

Assembly Missing Artifacts​

Symptom: repo-assemble fails with "Missing required artifacts" listing files like apps/background/dist/background.js.

Cause: The assembly runs before dependent apps have built, or a build failed silently.

Fix:

  1. Run pnpm build from the product root (builds all packages)
  2. Or run pnpm build:chrome which runs the full pipeline including dependencies
  3. Check that each app's Vite build succeeds (e.g. pnpm dev:main then stop and inspect apps/main/dist)