initial commit

docs/troubleshooting.md

@@ -0,0 +1,190 @@
+# 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`:
+
+```typescript
+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:
+   ```bash
+   which yt-dlp
+   ```
+
+2. If not found, set `YT_DLP_PATH` in `.env.local`:
+   ```bash
+   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):
+```bash
+# 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:
+```bash
+# 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:
+```bash
+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:
+  ```bash
+  NODE_OPTIONS="--max-old-space-size=4096" npm run dev
+  ```
+
+---
+
+## Still Having Issues?
+
+1. Check the [Setup Guide](./setup.md) for installation issues
+2. Review [Configuration](./configuration.md) 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