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

// 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 with detailed information.