# Mediaconvert Diagnostics

> 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.

- Skill: `aws-samples/mediaconvert-diagnostics` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add aws-samples/mediaconvert-diagnostics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/mediaconvert-diagnostics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/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

| 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

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

| 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 |