BetterSEQTA-Plus/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Published version: docs.betterseqta.org/troubleshooting/

Having issues with BetterSEQTA+ development? This guide covers the most common problems and their solutions.

Table of Contents

• Installation Issues
• Development Server Issues
• Browser Extension Issues
• Plugin Development Issues
• Build Issues
• Still Stuck?

Installation Issues

❌ "npm install" fails with peer dependency errors

Problem: You see errors about peer dependencies or conflicting packages.

Solution:

rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

❌ "Cannot find module" errors

Problem: Node.js can't find required packages.

Solutions:

1. Clear and reinstall:

   rm -rf node_modules
   npm install --legacy-peer-deps
   

2. Check Node.js version:

   node --version  # Should be v16 or higher
   

3. Try with npm cache clean:

   npm cache clean --force
   npm install --legacy-peer-deps
   

❌ Permission errors on macOS/Linux

Problem: "EACCES" or permission denied errors.

Solution:

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Development Server Issues

❌ "npm run dev" fails

Problem: Development server won't start.

Solutions:

1. Check if port is in use:

   lsof -i :5173  # Kill the process using the port
   

2. Clear dist folder:

   rm -rf dist
   npm run dev
   

3. Check for TypeScript errors:

   npx tsc --noEmit  # Check for type errors
   

❌ Changes not reflecting in browser

Problem: You make code changes but don't see them in the browser.

Solutions:

1. Reload the extension:

   • Go to chrome://extensions
   • Find BetterSEQTA+ and click the refresh icon
   • Refresh your SEQTA page

2. Check if dev server is running:

   • Look for "Build completed" in your terminal
   • If not, restart npm run dev

3. Hard refresh the page:

   • Press Ctrl+Shift+R (or Cmd+Shift+R on Mac)

Browser Extension Issues

❌ Extension doesn't load in Chrome

Problem: Extension appears in chrome://extensions but doesn't work.

Solutions:

1. Check for errors:

   • Go to chrome://extensions
   • Click "Errors" button on BetterSEQTA+
   • Fix any JavaScript errors shown

2. Verify manifest:

   • Check if dist/manifest.json exists
   • Ensure it has proper structure

3. Check permissions:

   • Extension needs permission to access SEQTA pages
   • Click "Details" → "Site access" → "On all sites"

❌ Extension doesn't appear on SEQTA pages

Problem: Extension loads but doesn't modify SEQTA.

Solutions:

1. Check if you're on a SEQTA Learn page:

   • URL should contain "seqta" or "learn"
   • Page title should include "SEQTA Learn"

2. Check browser console:

   • Press F12 → Console tab
   • Look for "[BetterSEQTA+]" messages
   • If no messages, extension isn't running

3. Verify page detection:

   • Extension only runs on actual SEQTA Learn pages
   • Test on a real SEQTA instance

❌ Settings page won't open

Problem: Clicking the extension icon doesn't open settings.

Solutions:

1. Check popup errors:

   • Right-click extension icon → "Inspect popup"
   • Look for JavaScript errors

2. Clear extension storage:

   // In browser console on any page:
   chrome.storage.local.clear()
   

3. Reload extension and try again

Plugin Development Issues

❌ My plugin doesn't appear in settings

Problem: Created a plugin but it's not showing up.

Solutions:

1. Check plugin registration:

   • Ensure your plugin is imported in src/plugins/index.ts
   • Verify pluginManager.registerPlugin(yourPlugin) is called

2. Check plugin structure:

   // Ensure your plugin has all required fields
   const myPlugin: Plugin = {
     id: "unique-id",      // Must be unique
     name: "Display Name",
     description: "What it does",
     version: "1.0.0",
     run: async (api) => {
       // Your code here
     }
   };
   

3. Check for errors:

   • Look in browser console for plugin loading errors

❌ Plugin settings not working

Problem: Plugin settings don't save or load properly.

Solutions:

1. Check settings definition:

   import { defineSettings, booleanSetting } from "@/plugins/core/settingsHelpers";
   
   const settings = defineSettings({
     myOption: booleanSetting({
       default: true,
       title: "My Option",
       description: "What this does"
     })
   });
   

2. Wait for settings to load:

   run: async (api) => {
     await api.settings.loaded;  // Wait for settings to load
     console.log(api.settings.myOption);  // Now you can use settings
   }
   

❌ Plugin API functions not working

Problem: api.seqta.onMount() or other API functions don't work.

Solutions:

1. Check selector specificity:

   // Be specific with selectors
   api.seqta.onMount(".home-page", (element) => {
     // Your code
   });
   

2. Wait for elements:

   // Some elements load after page navigation
   api.seqta.onPageChange((page) => {
     if (page === "home") {
       api.seqta.onMount(".home-content", (element) => {
         // Now element should exist
       });
     }
   });
   

Build Issues

❌ "npm run build" fails

Problem: Production build fails with errors.

Solutions:

1. Check TypeScript errors:

   npx tsc --noEmit
   

2. Clear cache and rebuild:

   rm -rf dist node_modules
   npm install --legacy-peer-deps
   npm run build
   

3. Check for import errors:

   • Ensure all imports use correct paths
   • Check for missing files

❌ Built extension doesn't work

Problem: npm run build succeeds but extension doesn't work.

Solutions:

1. Test the built extension:

   • Load the dist folder as unpacked extension
   • Check console for errors

2. Compare with dev version:

   • If dev works but build doesn't, there might be a build configuration issue

3. Check manifest generation:

   • Verify dist/manifest.json looks correct
   • Compare with working version

Common Error Messages

"Cannot access contents of the URL"

• Cause: Extension permissions issue
• Fix: Go to chrome://extensions → BetterSEQTA+ → Details → Site access → "On all sites"

"Extension context invalidated"

• Cause: Extension was reloaded while page was open
• Fix: Refresh the SEQTA page

"Uncaught ReferenceError: browser is not defined"

• Cause: Missing webextension-polyfill import
• Fix: Add import browser from "webextension-polyfill"; at top of file

"Module not found: Can't resolve '@/...' "

• Cause: TypeScript path mapping issue
• Fix: Check tsconfig.json and vite.config.ts for path configuration

Performance Issues

Extension makes SEQTA slow

1. Check for memory leaks:

   • Use Chrome DevTools → Performance tab
   • Look for growing memory usage

2. Optimize plugin code:

   • Remove unnecessary listeners
   • Clean up intervals/timeouts
   • Use efficient selectors

3. Profile your changes:

   • Test with extension disabled vs enabled
   • Identify which plugin is causing issues

Still Stuck?

If none of these solutions work:

1. 🔍 Search existing issues: GitHub Issues

2. 💬 Ask on Discord: Join our server - fastest way to get help!

3. 📝 Create a new issue: Include:

   • Your operating system
   • Node.js version (node --version)
   • Browser version
   • Exact error message
   • Steps to reproduce
   • What you've already tried

4. 📧 Email us: betterseqta.plus@gmail.com for urgent issues

Getting More Debug Info

Enable verbose logging

Add this to your plugin's run function:

console.log("[DEBUG] Plugin starting:", api);

Check extension background page

1. Go to chrome://extensions
2. Click "Details" on BetterSEQTA+
3. Click "Inspect views: background page"
4. Check console for background script errors

Export debug info

Run this in browser console on a SEQTA page:

console.log("Extension info:", {
  version: chrome.runtime.getManifest().version,
  url: window.location.href,
  userAgent: navigator.userAgent,
  storage: await chrome.storage.local.get()
});

Remember: Don't give up! Every developer faces these issues. The community is here to help, and solving these problems makes you a better developer. 💪