Video Generation Troubleshooting

Diagnose and fix video generation issues.

Check Video Status

1. Go to Videos in your dashboard
2. Find the affected video
3. Check the status and any error messages

Video Statuses

Common Failure Reasons

Missing Avatar

Error: “User does not have a configured avatar”

Fix:

1. Go to Settings > Profile
2. Connect your HeyGen account
3. Select or create an avatar

Invalid Script Variables

Error: “Script contains invalid variable: {{unknown_field}}”

Fix:

1. Edit the campaign script
2. Remove or replace invalid variables
3. Use only supported variables

Script Too Long

Error: “Script exceeds maximum length”

Limits:

• Maximum: 500 words
• Recommended: Under 250 words

Fix: Shorten your script.

HeyGen Service Error

Error: “External video service unavailable”

Fix:

1. Check HeyGen Status 
2. Wait for service recovery
3. Videos will auto-retry

Video Quality Issues

Audio Sync Problems

Cause: Complex pronunciation or unusual names.

Fix:

1. Use phonetic spelling in scripts
2. Add pronunciation hints: John (pronounced "Jon")
3. Simplify complex terms

Visual Artifacts

Cause: Avatar rendering issues.

Fix:

1. Try regenerating the video
2. Use a different avatar
3. Contact support if persistent

Wrong Language

Cause: Avatar/voice mismatch.

Fix:

1. Check avatar language setting
2. Ensure script matches avatar language
3. Use appropriate voice model

Regenerating Videos

To regenerate a failed video:

1. Go to Videos
2. Find the failed video
3. Click Regenerate

Or via API:

curl -X POST https://api.leadwarmer.net/api/v1/videos/{id}/regenerate \
  -H "Authorization: Bearer {token}"

Performance Optimization

Reduce Generation Time

1. Shorter scripts - Under 150 words
2. Simple variables - Avoid complex custom fields
3. Off-peak hours - Less queue congestion

Batch Processing

For high volume, videos are processed in batches:

• Batch size: 10 videos
• Batch interval: 1 minute
• Priority queue available for Enterprise

Monitoring Video Generation

Dashboard Metrics

View in Analytics > Video Generation:

• Generation success rate
• Average generation time
• Failure reasons breakdown

Webhook Notifications

Configure callbacks for video status:

{
  "video_status_webhook": "https://your-app.com/webhook",
  "notify_on": ["completed", "failed"]
}

Error Codes Reference

Getting Help

For persistent issues:

1. Note the video ID and error code
2. Screenshot the error message
3. Contact support@leadwarmer.net