1# Stream Gotchas
2 
3## Common Errors
4 
5### "ERR_NON_VIDEO"
6 
7**Cause:** Uploaded file is not a valid video format
8**Solution:** Ensure file is in supported format (MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime)
9 
10### "ERR_DURATION_EXCEED_CONSTRAINT"
11 
12**Cause:** Video duration exceeds `maxDurationSeconds` constraint
13**Solution:** Increase `maxDurationSeconds` in direct upload config or trim video before upload
14 
15### "ERR_FETCH_ORIGIN_ERROR"
16 
17**Cause:** Failed to download video from URL (upload from URL)
18**Solution:** Ensure URL is publicly accessible, uses HTTPS, and video file is available
19 
20### "ERR_MALFORMED_VIDEO"
21 
22**Cause:** Video file is corrupted or improperly encoded
23**Solution:** Re-encode video using FFmpeg or check source file integrity
24 
25### "ERR_DURATION_TOO_SHORT"
26 
27**Cause:** Video must be at least 0.1 seconds long
28**Solution:** Ensure video has valid duration (not a single frame)
29 
30## Troubleshooting
31 
32### Video stuck in "inprogress" state
33- **Cause**: Processing large/complex video
34- **Solution**: Wait up to 5 minutes for processing; use webhooks instead of polling
35 
36### Signed URL returns 403
37- **Cause**: Token expired or invalid signature
38- **Solution**: Check expiration timestamp, verify JWK is correct, ensure clock sync
39 
40### Live stream not connecting
41- **Cause**: Invalid RTMPS URL or stream key
42- **Solution**: Use exact URL/key from API, ensure firewall allows outbound 443
43 
44### Webhook signature verification fails
45- **Cause**: Incorrect secret or timestamp window
46- **Solution**: Use exact secret from webhook setup, allow 5-minute timestamp drift
47 
48### Video uploads but isn't visible
49- **Cause**: `requireSignedURLs` enabled without providing token
50- **Solution**: Generate signed token or set `requireSignedURLs: false` for public videos
51 
52### Player shows infinite loading
53- **Cause**: CORS issue with allowedOrigins
54- **Solution**: Add your domain to `allowedOrigins` array
55 
56## Limits
57 
58| Resource | Limit |
59|----------|-------|
60| Max file size | 30 GB |
61| Max frame rate | 60 fps (recommended) |
62| Max duration per direct upload | Configurable via `maxDurationSeconds` |
63| Token generation (API endpoint) | 1,000/day recommended (use signing keys for higher) |
64| Live input outputs (simulcast) | 5 per live input |
65| Webhook retry attempts | 5 (exponential backoff) |
66| Webhook timeout | 30 seconds |
67| Caption file size | 5 MB |
68| Watermark image size | 2 MB |
69| Metadata keys per video | Unlimited |
70| Search results per page | Max 1,000 |
71 
72## Performance Issues
73 
74### Upload is slow
75- **Cause**: Large file size or network constraints
76- **Solution**: Use TUS resumable upload, compress video before upload, check bandwidth
77 
78### Playback buffering
79- **Cause**: Network congestion or low bandwidth
80- **Solution**: Use ABR (adaptive bitrate) with HLS/DASH, reduce max bitrate
81 
82### High processing time
83- **Cause**: Complex video codec, high resolution
84- **Solution**: Pre-encode with H.264 (most efficient), reduce resolution
85 
86## Type Safety
87 
88```typescript
89// Error response type
90interface StreamError {
91  success: false;
92  errors: Array<{
93    code: number;
94    message: string;
95  }>;
96}
97 
98// Handle errors
99async function uploadWithErrorHandling(url: string, file: File) {
100  const formData = new FormData();
101  formData.append('file', file);
102  const response = await fetch(url, { method: 'POST', body: formData });
103  const result = await response.json();
104  
105  if (!result.success) {
106    throw new Error(result.errors[0]?.message || 'Upload failed');
107  }
108  return result;
109}
110```
111 
112## Security Gotchas
113 
1141. **Never expose API token in frontend** - Use direct creator uploads
1152. **Always verify webhook signatures** - Prevent spoofed notifications
1163. **Set appropriate token expiration** - Short-lived for security
1174. **Use requireSignedURLs for private content** - Prevent unauthorized access
1185. **Whitelist allowedOrigins** - Prevent hotlinking/embedding on unauthorized sites
119 
120## In This Reference
121 
122- [README.md](./README.md) - Overview and quick start
123- [configuration.md](./configuration.md) - Setup and config
124- [api.md](./api.md) - On-demand video APIs
125- [api-live.md](./api-live.md) - Live streaming APIs
126- [patterns.md](./patterns.md) - Full-stack flows, best practices
127 
128## See Also
129 
130- [workers](../workers/) - Deploy Stream APIs securely
131