downlink/docs/troubleshooting.md

Troubleshooting Guide

Common Issues and Solutions

Error: stdout maxBuffer length exceeded

Symptoms:

• API returns 500 error
• Error message: RangeError: stdout maxBuffer length exceeded
• Happens with long videos or videos with many format options

Cause: Node.js's exec function has a default maxBuffer of 1MB. For long videos, yt-dlp returns very large JSON output (especially with storyboard fragments) that exceeds this limit.

Solution: The code now uses a 10MB buffer. If you encounter this error again, you can increase it further in lib/youtube.ts:

await execAsync(command, { maxBuffer: 20 * 1024 * 1024 }); // 20MB buffer

Status: ✅ Fixed in current version

---

Error: yt-dlp command not found

Symptoms:

• Error: yt-dlp: command not found
• API returns 500 error

Cause: yt-dlp is not in your system PATH or the path in .env.local is incorrect.

Solution:

1. Check if yt-dlp exists:

   which yt-dlp
   

2. If not found, set YT_DLP_PATH in .env.local:

   YT_DLP_PATH=/full/path/to/yt-dlp
   

3. Restart the dev server

Status: ✅ Fixed with environment variable configuration

---

Error: Failed to get video info

Symptoms:

• API returns 500 error
• Generic error message: "Failed to get video info"

Possible Causes:

1. Invalid YouTube URL - Check URL format
2. Video is private/restricted - Video may not be accessible
3. Network issues - Check internet connection
4. yt-dlp needs update - Update yt-dlp: pip install --upgrade yt-dlp

Solution: Check server logs for detailed error messages. The logs will show the actual yt-dlp error.

---

Warning: No supported JavaScript runtime

Symptoms:

• Warning in logs: No supported JavaScript runtime could be found
• Some formats may be missing

Cause: yt-dlp needs a JavaScript runtime for some YouTube features. This is optional but recommended.

Solution: Install a JavaScript runtime (optional):

# Install Node.js (if not already installed)
brew install node

# Or install deno
brew install deno

Note: This is a warning, not an error. The app will still work, but some formats may be unavailable.

---

Download fails but info works

Symptoms:

• /api/info works fine
• /api/download fails

Possible Causes:

1. Disk space - Check available disk space
2. Permissions - Ensure write permissions for downloads/ and public/downloads/
3. ffmpeg missing - Required for audio conversion (MP3, WAV)

Solution:

1. Check disk space: df -h
2. Check permissions: ls -la downloads/ public/downloads/
3. Install ffmpeg: brew install ffmpeg

---

Files not cleaning up

Symptoms:

• Downloaded files accumulate in public/downloads/
• Disk space fills up

Cause: No automatic cleanup is implemented yet.

Solution: Manually clean up old files:

# Remove files older than 24 hours
find public/downloads/ -type f -mtime +1 -delete

Future: Automatic cleanup will be added in a future update.

---

Environment variable not loading

Symptoms:

• .env.local exists but variables aren't being used
• Still using default yt-dlp path

Solution:

1. Ensure file is named exactly .env.local (not .env.local.txt)
2. Restart the dev server completely (stop and start)
3. Check server startup logs for: Environments: .env.local
4. Verify no syntax errors in .env.local (no spaces around =)

---

Getting Help

Check Server Logs

The dev server logs show detailed error information. Look for:

• [getVideoInfo] Using yt-dlp path: - Confirms path is loaded
• Error getting video info: - Shows actual error
• POST /api/info 500 - HTTP status codes

Enable Debug Logging

Debug logging is automatically enabled in development mode. Check console output for:

• yt-dlp path being used
• Command execution errors
• File operation errors

Test yt-dlp Directly

Test yt-dlp outside the app:

yt-dlp --dump-json --no-download "https://www.youtube.com/watch?v=VIDEO_ID"

If this fails, the issue is with yt-dlp configuration, not the app.

---

Performance Issues

Slow API Responses

• Normal: 5-10 seconds for video info
• Normal: 30-60+ seconds for downloads (depends on video length)
• If slower, check network connection and yt-dlp version

High Memory Usage

• Large videos with many formats use more memory
• Consider increasing Node.js memory limit if needed:

  NODE_OPTIONS="--max-old-space-size=4096" npm run dev
  

---

Still Having Issues?

1. Check the Setup Guide for installation issues
2. Review Configuration for environment variables
3. Check server logs for detailed error messages
4. Test yt-dlp directly from command line
5. Ensure all dependencies are installed and up to date