> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videobgremover.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common video background removal problems. Resolve API errors, handle large files, optimize processing, and achieve perfect results with our guide.

## Common Issues

### Insufficient Credits (402 Error)

**Problem**: You don't have enough credits to process the video.

**Solution**: Check your credit balance and top up if needed.

<CodeGroup>
  ```bash cURL theme={"dark"}
  # Check credit balance
  curl -X GET https://api.videobgremover.com/v1/credits \
    -H "X-Api-Key: $API_KEY"

  # Response shows remaining credits
  {
    "total_credits": 100,
    "remaining_credits": 5,
    "used_credits": 95
  }
  ```

  ```typescript Node.js theme={"dark"}
  const client = new VideoBGRemoverClient('your_api_key')

  try {
    const credits = await client.credits()
    console.log(`Remaining credits: ${credits.remainingCredits}`)
    
    if (credits.remainingCredits < 10) {
      console.log('⚠️ Low credits. Consider topping up.')
    }
  } catch (error) {
    console.log('Failed to check credits:', error.message)
  }
  ```

  ```python Python theme={"dark"}
  client = VideoBGRemoverClient('your_api_key')

  try:
      credits = client.credits()
      print(f"Remaining credits: {credits.remaining_credits}")
      
      if credits.remaining_credits < 10:
          print('⚠️ Low credits. Consider topping up.')
  except Exception as e:
      print(f'Failed to check credits: {e}')
  ```
</CodeGroup>

### Invalid API Key (401 Error)

**Problem**: Your API key is invalid or missing.

**Solutions**:

1. Check your API key format: `vbr_` followed by 32 characters
2. Verify the key exists in your [API Management](https://videobgremover.com/api-management) dashboard
3. Ensure you're using the correct header: `X-Api-Key`

<CodeGroup>
  ```bash cURL theme={"dark"}
  # Correct format
  curl -H "X-Api-Key: vbr_your_32_character_key_here" ...

  # ❌ Wrong header name
  curl -H "Authorization: Bearer vbr_..." ...

  # ❌ Wrong key format  
  curl -H "X-Api-Key: invalid_key" ...
  ```

  ```typescript Node.js theme={"dark"}
  // ✅ Correct
  const client = new VideoBGRemoverClient('vbr_your_32_character_key')

  // ❌ Wrong format
  const client = new VideoBGRemoverClient('invalid_key')
  ```

  ```python Python theme={"dark"}
  # ✅ Correct
  client = VideoBGRemoverClient('vbr_your_32_character_key')

  # ❌ Wrong format
  client = VideoBGRemoverClient('invalid_key')
  ```
</CodeGroup>

### File Too Large (413 Error)

**Problem**: Your video file exceeds the 1GB limit.

**Solutions**:

1. Compress your video before uploading
2. Use a shorter video clip
3. Reduce video resolution or quality

### Job Not Found (404 Error)

**Problem**: The job ID doesn't exist or doesn't belong to your account.

**Solutions**:

1. Verify the job ID is correct
2. Check that you're using the same API key that created the job
3. Jobs expire after 24 hours - create a new one if needed

### Processing Failed

**Problem**: The job status shows "failed" with an error message.

**Common causes and solutions**:

For specific error messages, check the API response and ensure your video meets the format requirements.

### WebM Transparency Not Working

**Problem:** WebM video appears opaque instead of transparent

**Solution:** Use the correct decoder

```bash theme={"dark"}
# ❌ Wrong - strips alpha channels
ffmpeg -i video.webm ...

# ✅ Correct - preserves alpha channels
ffmpeg -c:v libvpx-vp9 -i video.webm ...
```

## SDK-Specific Issues

### Import Errors

<CodeGroup>
  ```typescript Node.js theme={"dark"}
  // ❌ Wrong import
  import VideoBGRemover from '@videobgremover/sdk'

  // ✅ Correct import
  import { VideoBGRemoverClient, Video } from '@videobgremover/sdk'
  ```

  ```python Python theme={"dark"}
  # ❌ Wrong import
  import videobgremover

  # ✅ Correct import
  from videobgremover import VideoBGRemoverClient, Video
  ```
</CodeGroup>

### FFmpeg Not Found

**Problem**: SDK can't find FFmpeg for composition operations.

**Solutions**:

1. Install FFmpeg: `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Ubuntu)
2. Ensure FFmpeg is in your PATH
3. Test with: `ffmpeg -version`

**Error you'll see**: When FFmpeg is not available, you'll get an error like:

```
Error: FFmpeg not found. Please install FFmpeg: Command 'ffmpeg' not found
```

<CodeGroup>
  ```bash Test FFmpeg theme={"dark"}
  # Test if FFmpeg is available
  ffmpeg -version

  # Should output version information
  # If you get "command not found", FFmpeg is not installed
  ```

  ```python Python theme={"dark"}
  # FFmpeg availability is checked automatically when creating MediaContext
  # If FFmpeg is not found, you'll see an error during SDK initialization
  from videobgremover import MediaContext

  try:
      ctx = MediaContext()
      print("✅ FFmpeg is available")
  except RuntimeError as e:
      print(f"❌ FFmpeg not found: {e}")
  ```

  ```typescript Node.js theme={"dark"}
  // FFmpeg availability is checked automatically when creating MediaContext
  // If FFmpeg is not found, you'll see an error during SDK initialization
  import { MediaContext } from '@videobgremover/sdk'

  try {
      const ctx = new MediaContext()
      console.log('✅ FFmpeg is available')
  } catch (error) {
      console.log('❌ FFmpeg not found:', error.message)
  }
  ```
</CodeGroup>

## Performance Issues

### Slow Processing

**Causes**:

* Large video files (>100MB)
* High resolution videos (4K+)
* Long videos (>5 minutes)

**Solutions**:

1. **Pre-process videos**: Reduce resolution to 1080p
2. **Split long videos**: Process in segments
3. **Optimize format**: Use MP4 with H.264 encoding

## Getting Help

If you're still having issues:

<CardGroup cols={2}>
  <Card title="📧 Email Support" icon="envelope">
    Contact [paul@videobgremover.com](mailto:paul@videobgremover.com) for technical support
  </Card>

  <Card title="🐛 Report Issues" icon="bug">
    Report bugs on [GitHub Issues](https://github.com/videobgremover/videobgremover-node/issues)
  </Card>
</CardGroup>