# 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