Mediaconvert Diagnostics

MediaConvert Diagnostics

When to use

Any AWS Elemental MediaConvert investigation where the console alone is insufficient — job failure analysis, encoding configuration, queue management, input/output troubleshooting, performance optimization, or DRM configuration.

Investigation workflow

Step 1 — Collect and triage

aws mediaconvert describe-endpoints
aws mediaconvert list-jobs --status ERROR --max-results 10 --endpoint-url <endpoint>
aws mediaconvert list-jobs --status COMPLETE --max-results 5 --endpoint-url <endpoint>
aws mediaconvert list-queues --endpoint-url <endpoint>
aws cloudwatch get-metric-statistics --namespace AWS/MediaConvert --metric-name JobsErrored --start-time <start> --end-time <end> --period 3600 --statistics Sum

Step 2 — Domain deep dive

aws mediaconvert get-job --id <job-id> --endpoint-url <endpoint>
aws mediaconvert get-job-template --name <template-name> --endpoint-url <endpoint>
aws mediaconvert list-presets --endpoint-url <endpoint>
aws s3 ls s3://<input-bucket>/<path>/
aws iam get-role --role-name <mediaconvert-role>

Step 3 — Detailed investigation

aws mediaconvert get-queue --name <queue-name> --endpoint-url <endpoint>
aws cloudwatch get-metric-statistics --namespace AWS/MediaConvert --metric-name JobsCompleted --start-time <start> --end-time <end> --period 3600 --statistics Sum
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=mediaconvert.amazonaws.com --max-results 10
aws kms describe-key --key-id <key-id>

Read references/guardrails.md before concluding on any MediaConvert issue.

Tool quick reference

Gotchas: MediaConvert

• Account-specific endpoint: MediaConvert uses account-specific endpoints. You must call describe-endpoints first and use the returned URL for all subsequent API calls.
• Job errors are in the job details: The error message and error code in the get-job response contain the specific failure reason. Always check this first.
• IAM role is required: MediaConvert needs an IAM role with S3 read access for inputs and S3 write access for outputs. The role must have a trust policy for mediaconvert.amazonaws.com.
• S3 bucket policy: The S3 bucket must allow the MediaConvert role to read inputs and write outputs. Cross-account access requires explicit bucket policy.
• Input file format: MediaConvert supports specific input containers and codecs. Not all video formats are supported. Check the supported codecs documentation.
• Output groups: Each job can have multiple output groups (File, HLS, DASH, CMAF, MS Smooth). Each group can have multiple outputs with different settings.
• Queue types: On-demand queues (pay per minute) and reserved queues (committed pricing). Reserved queues have a fixed number of reserved transcode slots (RTS).
• Accelerated transcoding: Available for specific codecs and resolutions. Costs more but significantly faster. Not all jobs qualify.
• DRM: Supports SPEKE (Secure Packager and Encoder Key Exchange) for content protection. Requires a key provider URL.
• Job priority: Jobs within a queue are processed by priority (1-50, default 0). Higher priority jobs are processed first.

Anti-hallucination rules

1. Always use the account-specific endpoint from describe-endpoints for all API calls.
2. Always check the job error message in get-job before diagnosing — it contains the specific failure reason.
3. Never assume all video codecs are supported — verify against MediaConvert's supported formats.
4. Reserved queues have fixed RTS capacity — they do not auto-scale.
5. Accelerated transcoding is not available for all codecs and resolutions.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

20 runbooks