yt2ai/docs/TROUBLESHOOTING.md

# YT2AI Troubleshooting Guide

## Quick Fixes

### "Bookmarklet doesn't work at all"
1. **Check installation:** Ensure the bookmark URL starts with `javascript:`
2. **Check Chrome version:** Must be Chrome 90+ on Android
3. **Test on YouTube:** Must be on a YouTube video page
4. **Clear browser cache:** Chrome → Settings → Privacy → Clear browsing data

### "No subtitles found"
1. **Verify subtitles exist:** Check if YouTube shows CC button
2. **Language requirement:** Only English auto-generated subtitles supported
3. **Try different video:** Some videos don't have auto-captions
4. **Wait and retry:** New videos may need time for caption generation

### "Loading forever" / Timeout
1. **Check network connection:** Ensure stable internet
2. **Try different network:** Switch between WiFi and mobile data
3. **Retry after timeout:** Wait 30 seconds, then try again
4. **Video length:** Very long videos (2+ hours) may timeout

## Common Issues

### Installation Problems

#### Issue: "Bookmark won't save the JavaScript code"
**Symptoms:** Bookmark saves but doesn't contain the full JavaScript code

**Solutions:**
1. **Copy complete code:** Ensure you copy the entire javascript: URL
2. **Manual typing:** Some browsers truncate paste - try typing "javascript:" first
3. **Alternative method:** Create bookmark first, then edit URL field
4. **Check for truncation:** Bookmark URL should be several KB long

**Prevention:**
- Always verify the bookmark URL starts with `javascript:(function(){`
- Test bookmark immediately after creating

#### Issue: "Chrome says 'This type of file can harm your computer'"
**Symptoms:** Chrome blocks bookmark creation with security warning

**Solutions:**
1. **Enable in Settings:** Chrome → Settings → Privacy and security → Site settings
2. **Temporary bypass:** Type `chrome://settings/content/unsandboxedPlugins`
3. **Alternative installation:** Use mobile installation method via QR code

**Note:** This is expected behavior - bookmarklets are active code.

### Execution Problems

#### Issue: "Please navigate to a specific YouTube video page"
**Symptoms:** Error message when tapping bookmark on YouTube

**Cause:** Bookmarklet requires specific video URL format

**Solutions:**
1. **Correct URL format:** Must be `/watch?v=` or `/shorts/` format
2. **Not on homepage:** Navigate to specific video first
3. **Not on playlist:** Go directly to video, not playlist page
4. **Valid video ID:** Ensure URL contains valid 11-character video ID

**Valid URLs:**
- ✅ `https://www.youtube.com/watch?v=dQw4w9WgXcQ`
- ✅ `https://youtu.be/dQw4w9WgXcQ`
- ✅ `https://www.youtube.com/shorts/dQw4w9WgXcQ`
- ❌ `https://www.youtube.com` (homepage)
- ❌ `https://www.youtube.com/playlist?list=...` (playlist)

#### Issue: "This bookmarklet only works on YouTube pages"
**Symptoms:** Error when not on YouTube

**Cause:** Safety check prevents execution on non-YouTube sites

**Solution:** Navigate to YouTube.com before using bookmarklet

### Subtitle Extraction Issues

#### Issue: "Video has subtitles but extraction fails"
**Symptoms:** YouTube shows CC button but bookmarklet finds no subtitles

**Possible Causes:**
1. **Language mismatch:** Only English auto-generated supported
2. **Manual captions:** User-uploaded captions not supported  
3. **API restrictions:** Subtitle service may block certain videos
4. **Geographic restrictions:** Some content blocked by region

**Solutions:**
1. **Check caption type:** Ensure "English (auto-generated)" is available
2. **Try different video:** Test with known working video
3. **Clear browser data:** Reset any API blocks
4. **Wait and retry:** API issues often resolve automatically

#### Issue: "CAPTCHA required" 
**Symptoms:** Modal asking to complete CAPTCHA verification

**Cause:** Subtitle API requires human verification (rate limiting)

**Solutions:**
1. **Complete CAPTCHA:** Follow the mobile-optimized instructions
2. **Wait before retry:** 5-10 minutes cooldown period
3. **Switch networks:** Different IP may avoid rate limiting
4. **Reduce frequency:** Avoid rapid successive extractions

**Prevention:**
- Wait at least 30 seconds between extractions
- Don't test repeatedly on same video
- Use different videos for testing

### Mobile-Specific Issues

#### Issue: "Touch targets too small"
**Symptoms:** Difficult to tap close buttons or UI elements

**Cause:** UI scaling issue on high-DPI displays

**Solutions:**
1. **Browser zoom:** Adjust Chrome zoom to 100%
2. **System display size:** Check Android display settings
3. **Update Chrome:** Ensure latest version
4. **Report issue:** Include device model and screen size

**Temporary workaround:** Use stylus or fingernail for precision

#### Issue: "Overlay doesn't fit screen"
**Symptoms:** Content cut off or requires scrolling

**Cause:** Responsive design issue with specific device

**Solutions:**
1. **Rotate device:** Try landscape orientation
2. **Close other tabs:** Free memory for proper rendering
3. **Restart browser:** Clear rendering cache
4. **Check zoom level:** Ensure 100% zoom

**Report needed:** Device model, screen resolution, Chrome version

#### Issue: "Performance is slow"
**Symptoms:** Long loading times, UI lag, browser unresponsive

**Cause:** Memory pressure or slow network

**Solutions:**
1. **Close background apps:** Free system memory
2. **Check available storage:** Ensure 1GB+ free space
3. **Restart Chrome:** Clear memory leaks
4. **Switch networks:** Test WiFi vs mobile data
5. **Update Chrome:** Performance improvements in newer versions

**Performance tips:**
- Use on newer Android devices (8.0+)
- Ensure good network connection
- Close unnecessary browser tabs

### Network and API Issues

#### Issue: "Network timeout" errors
**Symptoms:** Extraction fails with timeout message after 30 seconds

**Cause:** Slow network or API server overload

**Solutions:**
1. **Check connection speed:** Test with speed test app
2. **Switch networks:** Try different WiFi or mobile data
3. **Retry later:** API servers may be temporarily overloaded
4. **Shorter videos:** Try with <10 minute videos first

**Network requirements:**
- Minimum: 1 Mbps download speed
- Recommended: 5+ Mbps for reliable operation

#### Issue: "API service unavailable"
**Symptoms:** Error indicating subtitle service is down

**Cause:** External API (downloadyoutubesubtitles.com) temporarily unavailable

**Solutions:**
1. **Wait and retry:** Usually resolves within 1-2 hours
2. **Check service status:** Visit downloadyoutubesubtitles.com directly
3. **Try different videos:** Some videos may still work
4. **Monitor announcements:** Check GitHub issues for outage reports

**No user action required:** This is a temporary external service issue

## Advanced Troubleshooting

### Debug Mode

#### Enable Debug Logging
Add `?debug=true` to YouTube URL:
```
https://www.youtube.com/watch?v=dQw4w9WgXcQ&debug=true
```

Then tap bookmarklet to get detailed console logs.

#### Reading Debug Output
Look for these patterns in browser console:
- `[YT2AI:INFO]` - Normal operation messages
- `[YT2AI:WARN]` - Warnings that don't break functionality
- `[YT2AI:ERROR]` - Errors that prevent operation
- `[YT2AI:DEBUG]` - Detailed operation information

#### Common Debug Messages
```
[YT2AI:INFO] Bookmarklet initialized
[YT2AI:DEBUG] Environment: mobile=true, android=true
[YT2AI:DEBUG] Video ID extracted: dQw4w9WgXcQ
[YT2AI:ERROR] Network timeout after 30000ms
```

### Chrome Developer Tools (Advanced)

#### Enable Developer Tools on Android
1. **Enable Developer Options:** Settings → About phone → Tap Build number 7 times
2. **Enable USB Debugging:** Settings → Developer options → USB debugging
3. **Connect to computer:** USB cable + Chrome on desktop
4. **Inspect device:** Chrome → chrome://inspect → Find your device

#### Useful Developer Tools Tabs
- **Console:** View JavaScript errors and debug messages
- **Network:** Monitor API requests and responses
- **Memory:** Check for memory leaks or high usage
- **Performance:** Profile execution timing

### Memory Investigation

#### Check Memory Usage
```javascript
// In console:
console.log('Memory:', performance.memory);
console.log('State:', window.__YT2AI__?.stateManager.getState());
```

#### Memory Warning Signs
- `usedJSHeapSize` > 50MB
- Browser becomes unresponsive
- Other tabs crash or reload
- Android shows "Chrome is using too much memory"

#### Memory Solutions
1. **Force cleanup:** Reload YouTube page
2. **Restart Chrome:** Force close and reopen
3. **Restart device:** Clear all memory
4. **Free storage:** Delete unused apps/files

## Error Codes Reference

### YT2AI Error Types

#### E001: Invalid YouTube Context
- **Message:** "This bookmarklet only works on YouTube pages"
- **Cause:** Not on youtube.com domain
- **Solution:** Navigate to YouTube first

#### E002: No Video ID Found
- **Message:** "Please navigate to a specific YouTube video page"  
- **Cause:** URL doesn't contain valid video ID
- **Solution:** Go to specific video page

#### E003: Network Timeout
- **Message:** "Network timeout after 30000ms"
- **Cause:** Slow connection or API overload
- **Solution:** Check network, retry later

#### E004: No Subtitles Available
- **Message:** "No English auto-generated subtitles found"
- **Cause:** Video lacks auto-captions
- **Solution:** Try different video

#### E005: API Service Error
- **Message:** "Subtitle extraction service temporarily unavailable"
- **Cause:** External API down
- **Solution:** Wait and retry

#### E006: CAPTCHA Required
- **Message:** "Human verification required"
- **Cause:** Rate limiting triggered
- **Solution:** Complete CAPTCHA, reduce usage frequency

#### E007: Memory Pressure
- **Message:** "Insufficient memory to complete operation"
- **Cause:** Low device memory
- **Solution:** Close apps, restart browser

## Device-Specific Issues

### Samsung Devices

#### Issue: "Bookmarklet won't execute"
**Cause:** Samsung Internet interference with Chrome

**Solutions:**
1. **Set Chrome as default:** Settings → Apps → Default apps → Browser
2. **Disable Samsung Internet:** If not needed
3. **Clear app preferences:** Reset default handlers

#### Issue: "UI elements too small"
**Cause:** Samsung's display scaling

**Solutions:**
1. **Adjust display size:** Settings → Display → Screen zoom
2. **Font size:** Settings → Display → Font size and style
3. **Chrome accessibility:** Chrome → Settings → Accessibility

### Pixel/Nexus Devices

Generally excellent compatibility - report any issues as bugs.

### OnePlus Devices

#### Issue: "Performance lag"
**Cause:** OxygenOS battery optimization

**Solutions:**
1. **Battery optimization:** Settings → Battery → Battery optimization → Chrome → Don't optimize
2. **Background app limits:** Settings → Privacy → Permission manager → Special app access

### Huawei Devices (with Google Services)

#### Issue: "Network connectivity issues"
**Cause:** Huawei network optimization

**Solutions:**
1. **Data saver:** Turn off data saver in network settings
2. **App network permissions:** Ensure Chrome has unrestricted network access

## Reporting Issues

### Before Reporting
1. **Try troubleshooting steps** above
2. **Test with debug mode** enabled
3. **Try different video** to isolate issue
4. **Check recent similar reports** in GitHub issues

### What to Include

#### Required Information
- **Device:** Make, model, Android version
- **Chrome version:** Chrome → Settings → About Chrome
- **Network type:** WiFi, 4G, 5G, etc.
- **Video URL:** That reproduces the issue
- **Error message:** Exact text if any
- **Steps to reproduce:** Numbered list

#### Helpful Additional Info
- **Debug console output:** Copy from Developer Tools
- **Screenshots:** Of error messages or UI issues
- **Network speed:** From speed test
- **Multiple devices:** Does issue occur on other devices?

#### Example Report Template
```
**Device:** Samsung Galaxy S21, Android 12
**Chrome Version:** 91.0.4472.120
**Network:** WiFi, ~50 Mbps
**Issue:** Overlay appears but extraction never completes

**Steps:**
1. Navigate to https://www.youtube.com/watch?v=dQw4w9WgXcQ
2. Tap YT2AI bookmark
3. See "YT2AI Ready!" message
4. Loading overlay appears but never finishes
5. After 30 seconds, no error message appears

**Console Output:**
[Paste debug console output here]

**Additional Notes:**
Works fine on different video (tested with jNQXAC9IVRw)
```

### Where to Report

#### GitHub Issues
- **Bugs:** Use bug report template
- **Feature requests:** Use feature request template
- **Questions:** Use discussion forum

#### Community Support
- **GitHub Discussions:** General questions and usage help
- **Reddit:** r/bookmarklets community
- **Stack Overflow:** Tag with `bookmarklet` and `youtube`

## Prevention Tips

### Best Practices
1. **Test installation:** Always verify bookmark works after creating
2. **Use on good network:** WiFi preferred for initial tests
3. **Start with short videos:** <5 minutes for first tests
4. **Keep Chrome updated:** Latest version has fewest issues
5. **Monitor memory:** Close unnecessary tabs during use

### Avoid Common Mistakes
1. **Don't spam-click:** Wait for completion before retrying
2. **Don't test on music videos:** Often lack subtitles
3. **Don't use on very new videos:** Captions take time to generate
4. **Don't use with VPN:** Can trigger API rate limiting
5. **Don't use in private browsing:** Some features may not work

---

**Still having issues?** Open a [GitHub issue](https://github.com/yt2ai/yt2ai-bookmarklet/issues) with detailed information.