Common Issues Troubleshooting

This document summarizes various issues you may encounter while using FlowPick, providing diagnostic steps and solutions organized by symptom.

Quick Issue Index

If you already know the issue type, jump directly to the corresponding section:

Diagnostic Tools & Tips

Before diving into troubleshooting, mastering these diagnostic tools can significantly improve efficiency.

Browser Developer Tools

Press F12 or Ctrl+Shift+I to open Developer Tools, focusing on these panels:

Common Error Message Quick Reference

When seeing these errors in Console, quickly locate the issue:

Generate Diagnostic Report

For complex issues, run this code in Console to generate a diagnostic report for submitting issues:

// FlowPick Diagnostic Report Generator
const report = {
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  language: navigator.language,
  fsaAvailable: 'showDirectoryPicker' in window,
  fsaSaveAvailable: 'showSaveFilePicker' in window,
  sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
  crossOriginIsolated: self.crossOriginIsolated,
  serviceWorker: 'serviceWorker' in navigator,
  storage: {
    quota: await navigator.storage?.estimate().catch(() => null),
  },
  timestamp: new Date().toISOString(),
}
console.log('FlowPick Diagnostic Report:', JSON.stringify(report, null, 2))

Media Detection Issues

Extension Cannot Detect Any Media

Symptom: After opening a page containing video/audio, clicking the FlowPick icon shows "No media resources detected" in the popup.

Diagnostic Steps:

1. Confirm media has loaded on page
   Before opening FlowPick, play video or audio for a few seconds first. Many websites use lazy loading strategies that only start loading media streams after user interaction.
2. Refresh page and retry
   The extension's media detection relies on monitoring network requests. If the extension was installed or activated after the page loaded, it may have missed initial requests. Refreshing triggers new network requests.
3. Check if extension is activated
   When clicking the extension icon, confirm the popup displays normally. If the popup cannot open, the extension may not be correctly installed or has been disabled.
4. Check if page uses non-standard protocols
   Some websites transmit media via WebSocket, WebRTC, or custom encryption protocols, which are outside FlowPick's detection scope.

Common Causes & Solutions:

Some Media Not Detected

Symptom: FlowPick detects some resources but is missing certain expected videos or audio files.

Possible Causes:

• Dynamic loading timing: Some media only loads when users scroll or click. Try interacting with the page before opening FlowPick
• Filter settings: Check if minimum file size filter is set, causing small files to be excluded. For filter configuration, see Configuration Reference — Filter Settings
• Non-standard MIME type: Server returns Content-Type not in FlowPick's recognition list. FlowPick currently recognizes 25+ MIME types, but some CDNs may use non-standard types

Incomplete Image Detection

Symptom: Not all images on the page appear in detection results.

Cause Analysis:

• Images in CSS background-image require full page rendering before detection
• Lazy-loaded images (loading="lazy") only load when scrolled into viewport
• <img> elements dynamically created via JavaScript may be inserted into DOM after extension scanning
• Canvas-rendered image content cannot be obtained through DOM detection

Recommendation: Scroll through the entire page before opening FlowPick to ensure all lazy-loaded content has been triggered.

Download Issues

Download Won't Start

Symptom: No response after clicking download button, or error appears immediately.

Diagnostic Steps:

1. Check browser download settings
   Confirm browser isn't blocking automatic downloads. In Chrome: Settings → Privacy and security → Site settings → Automatic downloads.
2. Check disk space
   Ensure sufficient free space on system disk. Video files can be large (several GB); confirm adequate space before downloading.
3. Check for conflicts with other download extensions
   Some download manager extensions may intercept or modify download requests. Try temporarily disabling other download-related extensions.
4. Check browser console for errors
   Press F12 to open Developer Tools, check Console panel for errors. Common errors include:
   • Failed to fetch: Network request failed
   • CORS error: Cross-origin request blocked
   • QuotaExceededError: Insufficient storage space

Slow Download Speed

Symptom: Download progress is slow, speed far below network bandwidth.

Influencing Factors & Optimization Suggestions:

Diagnostic Flow:

Slow download speed
    │
    ├── Concurrency < 4?
    │   └── Yes → Increase concurrency to 4-6, observe speed change
    │
    ├── Large speed fluctuations?
    │   └── Yes → May be CDN throttling, try reducing concurrency to 2-3
    │
    ├── All downloads slow?
    │   └── Yes → Check network bandwidth, close other bandwidth-consuming apps
    │
    └── Only specific sites slow?
        └── Yes → That site's CDN may throttle, try different quality

Download Fails Midway

Symptom: Download stops with error after reaching certain percentage.

Common Errors & Handling:

HTTP 403 Forbidden

Segment URLs may contain time-sensitive tokens; server rejects access after expiration. Solutions:

• Refresh page to get new stream address
• Complete download promptly to avoid token expiration
• For HLS streams, token is usually in M3U8 manifest; re-fetching manifest suffices

HTTP 404 Not Found

Segment deleted from server (common with live replays). Solutions:

• Confirm stream is still available
• Try selecting different quality (different qualities may use different segment files)

Network connection interruption

Automatic retry mechanism handles temporary network fluctuations. If persistently failing:

• Check network connection stability
• Reduce concurrent thread count to reduce simultaneous connections
• Check firewall or proxy settings

CORS Error

Online tool version restricted by browser same-origin policy. Solutions:

• Use browser extension version (extensions have broader network permissions)
• If using online tools, confirm stream URL's server allows cross-origin requests

File Won't Play After Download

Symptom: Download complete, but video/audio file cannot be opened in player.

Diagnosis & Repair:

1. Try different players
   Some players have limited support for specific codecs or containers. Recommended players for testing:
   • VLC Media Player (best compatibility)
   • MPC-HC
   • PotPlayer
2. Check file size
   If file size significantly smaller than expected (e.g., only few KB), may have downloaded M3U8 manifest instead of actual video. Confirm correct resource selected.
3. Try different quality
   Segments of certain qualities may have encoding issues. Try downloading lower or higher quality version.
4. Use VLC repair feature
   VLC provides built-in AVI/MP4 repair:
   • Open VLC → Media → Convert/Save
   • Add file → Convert/Save
   • Select output format → Start
5. Check if merge complete
   If browser crashed or network interrupted during download, merge may be incomplete. Re-downloading usually resolves this.

Large File Download Failure

Symptom: Browser freezes or crashes when downloading large files (>1GB).

Cause: In Blob mode, entire file must be loaded into memory before triggering download. For very large files, this may cause memory exhaustion.

Solutions:

• Use File System Access API save directory feature; files written directly to disk without consuming memory
• If browser doesn't support FSA API, FlowPick automatically uses StreamSaver.js streaming write
• If both streaming writes unavailable, Blob mode has 1.5GB hard limit; files exceeding this size will be rejected

Merge Issues

Audio/Video Desync After Merge

Symptom: Time offset exists between video and audio tracks.

Cause: This typically occurs with DASH streams where video and audio segment timestamps are not perfectly aligned. FlowPick uses -c copy mode for merging without re-encoding, so cannot fix timestamp offset.

Solutions:

• Try selecting different quality (A/V sync may differ across qualities)
• Use FFmpeg command-line tool for manual re-encoding:

ffmpeg -i output.mp4 -c:v libx264 -c:a aac -async 1 fixed.mp4

Merge Process Stuck

Symptom: Progress bar stays at "Merging" stage for extended time.

Cause Analysis:

• FFmpeg WASM requires longer time when processing many segments
• When SharedArrayBuffer unavailable in multithreaded mode, FFmpeg falls back to single-thread, significantly reducing speed
• Insufficient memory causes WASM to run slowly

Recommendations:

• Wait for merge completion; large file merges may take several minutes
• Selecting TS output format skips FFmpeg transcoding, using direct binary concatenation (completes in seconds)
• Close other tabs consuming memory

Browser Compatibility Issues

SharedArrayBuffer Unavailable

Symptom: Console shows SharedArrayBuffer is not defined or FFmpeg running in single-thread mode.

Cause: SharedArrayBuffer requires correct security headers on page. FlowPick website already configured:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

If your deployment environment lacks these headers, FFmpeg automatically falls back to single-thread mode; functionality unaffected but slower.

File System Access API Unavailable

Symptom: No "Select Save Directory" button, or no response when clicked.

Support Status:

On unsupported browsers, FlowPick automatically uses browser default download method.

StreamSaver.js Not Working

Symptom: Console shows StreamSaver-related errors.

Possible Causes:

• Service Worker registration failed (some browser policies prohibit)
• mitm.html page cannot load
• Browser doesn't support WritableStream

FlowPick automatically degrades to Blob mode; functionality unaffected.

Extension-Specific Issues

Extension Icon Not Showing

1. Click puzzle icon in browser toolbar (extension management)
2. Find FlowPick
3. Click pin icon to pin it to toolbar

Extension Automatically Disabled

Chrome may disable extensions under these circumstances:

• Extension update requires new permissions
• Browser detects suspicious behavior
• Developer mode extensions disabled after browser restart

Solution: Re-enable FlowPick on chrome://extensions page.

Keyboard Shortcut Conflicts

Default shortcuts Alt+Shift+F and Alt+Shift+D may conflict with other extensions or system shortcuts.

How to modify:

1. Open chrome://extensions/shortcuts
2. Find FlowPick
3. Set new shortcut combination

Network Troubleshooting

Proxy/VPN Environment

If using proxy or VPN, downloads may be affected:

Corporate Network Environment

Corporate networks typically have stricter security policies, potentially causing these issues:

• Firewall blocking non-standard ports: Some streaming uses non-80/443 ports, may be blocked by corporate firewall
• Service Worker disabled: Some enterprise management policies prohibit Service Workers, causing StreamSaver.js unavailability
• Extension installation restricted: Enterprise-managed browsers may prohibit installing non-whitelisted extensions

Recommendation: In corporate network environments, prioritize online tool version (if accessible), or contact IT department about network policies.

Getting Help

If above solutions don't resolve your issue:

1. Check GitHub Issues for similar problems
2. Submit new issue with following information:
   • Browser and version
   • FlowPick version
   • Issue description and reproduction steps
   • Browser console error log (F12 → Console)
   • Problem page URL (if publicly accessible)
   • Output from diagnostic report