Guides

Troubleshooting

Common issues and how to resolve them.

Troubleshooting

Common issues and how to resolve them.

Quick Diagnostics

Before diving into specific issues:

  1. Check your internet connection - Many issues are network-related
  2. Try refreshing the page - Clears temporary glitches
  3. Clear browser cache - Resolves stale data issues
  4. Check Shopify status - Issues may be upstream

Installation & Authentication

App Won't Install

Symptoms:

  • Error during OAuth flow
  • Redirect fails
  • "Access denied" message

Solutions:

  1. Verify you have store owner or admin access
  2. Check your Shopify plan supports apps
  3. Clear browser cookies and try again
  4. Disable browser extensions that might interfere
  5. Try a different browser

Session Expired

Symptoms:

  • Suddenly logged out
  • "Session invalid" errors
  • Redirected to Shopify login

Solutions:

  1. Refresh the page (new session will be created)
  2. Clear Shopify admin cookies
  3. Sign out and back into Shopify
  4. Reinstall the app if persistent

"Shop Not Found" Error

Symptoms:

  • Error when accessing PeerScripts
  • Shop data not loading

Solutions:

  1. Verify you're accessing from Shopify admin
  2. Check the URL includes correct shop parameter
  3. Try reinstalling the app
  4. Contact support if persistent

Data & Syncing

Data Not Syncing

Symptoms:

  • Old data showing
  • New orders/products missing
  • Sync indicator shows stale data

Solutions:

  1. Click "Sync Now" to force refresh
  2. Wait a few minutes for large data sets
  3. Check Shopify API status
  4. Verify API permissions haven't changed

Incorrect Data Showing

Symptoms:

  • Numbers don't match Shopify admin
  • Missing items
  • Wrong values

Solutions:

  1. Check the date range selected
  2. Verify filters aren't excluding data
  3. Force a manual sync
  4. Compare raw data in both systems
  5. Report to support with specific examples

Sync Takes Too Long

Symptoms:

  • Sync spinner never stops
  • Progress stuck at percentage
  • Timeout errors

Solutions:

  1. Large stores take longer - be patient
  2. Try syncing during off-peak hours
  3. Sync specific data types individually
  4. Contact support for very large stores

Scans & Analysis

Scan Won't Start

Symptoms:

  • "Start Scan" does nothing
  • Error when initiating scan
  • Scan stays in "pending" state

Solutions:

  1. Refresh the page and try again
  2. Check you have permission to run scans
  3. Verify the theme/data source exists
  4. Wait if another scan is running
  5. Try a different scan type (quick vs full)

Scan Takes Too Long

Symptoms:

  • Progress stuck
  • Scan running for hours
  • Timeout errors

Solutions:

  1. Large themes may take 5-10 minutes
  2. Try a quick scan instead
  3. Check for extremely large files
  4. Cancel and restart if stuck > 15 minutes

Scan Fails

Symptoms:

  • "Scan failed" error
  • Incomplete results
  • Error messages in results

Solutions:

  1. Note the error message
  2. Try running the scan again
  3. Try a different scan type
  4. Check for unusual theme structure
  5. Contact support with error details

Results Seem Wrong

Symptoms:

  • False positives
  • Missing obvious issues
  • Incorrect severity

Solutions:

  1. Use "Ignore" for known false positives
  2. Report persistent false positives
  3. Check if issue was recently fixed
  4. Verify file hasn't changed since scan

Performance Issues

PeerScripts Is Slow

Symptoms:

  • Pages take long to load
  • Actions are delayed
  • General sluggishness

Solutions:

  1. Check your internet connection
  2. Clear browser cache
  3. Close other browser tabs
  4. Try during off-peak hours
  5. Use Chrome for best performance

Dashboard Not Loading

Symptoms:

  • Blank dashboard
  • Loading spinner never stops
  • Partial data showing

Solutions:

  1. Refresh the page
  2. Check browser console for errors
  3. Clear browser cache
  4. Try incognito/private mode
  5. Contact support if persistent

Charts Not Displaying

Symptoms:

  • Empty chart areas
  • "No data" messages
  • Broken chart visuals

Solutions:

  1. Check the date range selected
  2. Verify data exists for the period
  3. Try a different browser
  4. Disable ad blockers
  5. Clear browser cache

AI Features

AI Not Responding

Symptoms:

  • Chat doesn't respond
  • Explanation Engine times out
  • "AI unavailable" errors

Solutions:

  1. Check internet connection
  2. Try a simpler question
  3. Refresh the chat panel
  4. Check AI settings in Settings
  5. Wait and retry (may be rate limited)

AI Gives Wrong Answers

Symptoms:

  • Inaccurate explanations
  • Irrelevant suggestions
  • Contradictory responses

Solutions:

  1. Rephrase your question
  2. Provide more context
  3. Ask more specific questions
  4. Check the raw data view
  5. Report persistent issues

Code Suggestions Don't Work

Symptoms:

  • Suggested code has errors
  • Can't apply suggestion
  • Suggestion breaks existing code

Solutions:

  1. Review suggestions before applying
  2. Make manual adjustments if needed
  3. Undo and try different approach
  4. Ask for explanation instead

Tickets & Sprints

Can't Create Tickets

Symptoms:

  • "Create Ticket" fails
  • Form won't submit
  • Error on save

Solutions:

  1. Check required fields are filled
  2. Verify you have create permission
  3. Refresh and try again
  4. Check for validation errors

Tickets Not Moving

Symptoms:

  • Drag and drop doesn't work
  • Status won't update
  • Board appears frozen

Solutions:

  1. Try clicking instead of dragging
  2. Refresh the page
  3. Check if sprint is locked
  4. Verify you have edit permission

Sprint Issues

Symptoms:

  • Can't start sprint
  • Tickets not appearing
  • Sprint metrics wrong

Solutions:

  1. Ensure tickets are assigned to sprint
  2. Check sprint dates are set
  3. Verify no other sprint is active
  4. Refresh the planning view

Action Center

Action Won't Execute

Symptoms:

  • Execute button disabled
  • Action stays pending
  • Error during execution

Solutions:

  1. Check if approval is required
  2. Verify you have execute permission
  3. Preview first to validate items
  4. Check for conflicts with other operations

Execution Fails Partially

Symptoms:

  • Some items fail
  • Error messages in results
  • Incomplete execution

Solutions:

  1. Review failure details
  2. Fix underlying issues
  3. Retry failed items individually
  4. Create ticket for persistent failures

Can't Rollback

Symptoms:

  • Rollback option missing
  • Rollback fails
  • Data not restored

Solutions:

  1. Check if action type supports rollback
  2. Verify rollback data was saved
  3. Check time hasn't exceeded retention
  4. Manual restore may be needed

Notifications

Not Receiving Emails

Symptoms:

  • No email notifications
  • Missing alerts
  • Digest not arriving

Solutions:

  1. Check spam/junk folder
  2. Verify email address in settings
  3. Check notification preferences
  4. Whitelist notification sender
  5. Check quiet hours settings

Too Many Notifications

Symptoms:

  • Inbox flooded
  • Alert fatigue
  • Irrelevant notifications

Solutions:

  1. Adjust notification settings
  2. Increase severity threshold
  3. Enable digest instead of individual
  4. Set up quiet hours

Browser-Specific Issues

Chrome

  • Clear cache: Settings > Privacy > Clear browsing data
  • Disable extensions: chrome://extensions
  • Check console: F12 > Console tab

Firefox

  • Clear cache: Settings > Privacy > Clear Data
  • Safe mode: Help > Restart with Add-ons Disabled
  • Check console: F12 > Console tab

Safari

  • Clear cache: Safari > Clear History
  • Disable extensions: Safari > Preferences > Extensions
  • Check console: Develop > Show Web Inspector

Edge

  • Clear cache: Settings > Privacy > Clear browsing data
  • Check extensions: edge://extensions
  • Check console: F12 > Console tab

Getting More Help

Before Contacting Support

Gather this information:

  1. Store domain
  2. Browser and version
  3. Steps to reproduce
  4. Screenshots of errors
  5. Browser console errors (F12)

Support Channels

  • Documentation: Search these docs first
  • FAQ: Check FAQ for common questions
  • GitHub Issues: Report bugs and request features
  • Email Support: Contact your account representative

Providing Good Bug Reports

Include:

  • What you expected to happen
  • What actually happened
  • Steps to reproduce
  • Error messages (exact text)
  • Screenshots if helpful
  • Browser/OS information

Status & Updates

Checking Service Status

  1. View the dashboard sync indicator
  2. Check Shopify status page
  3. Monitor Supabase status
  4. Review recent update notes

Known Issues

Check the release notes and GitHub issues for known issues and planned fixes.

Recovery Procedures

Data Recovery

If you accidentally deleted or modified data:

  1. Check Action Center history for rollback
  2. Review Shopify's own history
  3. Contact support for database recovery
  4. Restore from backups if available

Account Recovery

If locked out:

  1. Try signing in through Shopify admin
  2. Clear all browser data
  3. Try a different browser
  4. Reinstall the app
  5. Contact support with store details

More in Guides

Best Practices

Recommended workflows, optimization strategies, and expert tips for getting the most out of PeerScripts.

Frequently Asked Questions

Answers to common questions about PeerScripts.

All Documentation