| name | mediaconvert-diagnostics |
| version | 1.0.0 |
| last_updated | 2025-04-12 |
| description | Use this skill to investigate and troubleshoot AWS Elemental MediaConvert problems by analyzing job failures, input/output configurations, queue management, encoding settings, IAM roles, performance, and DRM configurations using structured runbooks. Activate when: job failures, stuck jobs, output errors, input file issues, codec support problems, output format errors, quality settings, queue management, reserved pricing, S3 input/output issues, IAM role problems, encoding speed, parallel job issues, content protection, key management, or the user says something is wrong with MediaConvert without naming specific symptoms.
|
| compatibility | Requires AWS CLI or SDK access with MediaConvert, S3, IAM, CloudWatch, CloudTrail, and optionally KMS permissions.
|
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
| Tool / API | When to use |
|---|
describe-endpoints | Get account-specific endpoint |
get-job | Job details and error messages |
list-jobs | Job history by status |
list-queues | Queue configuration |
get-job-template | Job template settings |
list-presets | Output presets |
get-queue | Queue details and pricing |
s3 ls | Verify input/output files |
iam get-role | MediaConvert service role |
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
- Always use the account-specific endpoint from describe-endpoints for all API calls.
- Always check the job error message in get-job before diagnosing — it contains the specific failure reason.
- Never assume all video codecs are supported — verify against MediaConvert's supported formats.
- Reserved queues have fixed RTS capacity — they do not auto-scale.
- Accelerated transcoding is not available for all codecs and resolutions.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
20 runbooks
| Category | IDs | Covers |
|---|
| A — Jobs | A1-A3 | Job failures, stuck jobs, output errors |
| B — Input | B1-B2 | Input file issues, codec support |
| C — Output | C1-C2 | Output format, quality settings |
| D — Queue | D1-D2 | Queue management, reserved pricing |
| E — Integration | E1-E2 | S3 input/output, IAM roles |
| F — Performance | F1-F2 | Encoding speed, parallel jobs |
| G — DRM | G1-G2 | Content protection, key management |
| Z — Catch-All | Z1 | General troubleshooting |
