[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7A7GG70WC606H6CFJFWRFG5":3,"skill-same:01M7A7GG70WC606H6CFJFWRFG5":152},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":6,"ownerDescription":50,"updatedAt":51,"install":52,"resources":65},"01M7A7GG70WC606H6CFJFWRFG5","ecr-push-pull-troubleshooter",null,"Diagnoses Amazon ECR push and pull failures through a fourteen-category diagnostic tree: authentication (docker login token expiry, IAM ecr:GetAuthorizationToken), repository policy vs IAM policy precedence, lifecycle policy prematurely deleting images, image size limit (10 GB), cross-region replication lag, KMS encryption key access denied, registry alias confusion (public vs private), scan-on-push findings blocking deployment, image tag immutability conflicts, docker manifest errors, pull-through cache misconfiguration, Fargate\u002FECS platform version vs image architecture mismatch (arm64 vs x86_64), layer download failures, and throttling. Walks symptoms to a verified root cause with evidence-backed probes; emits ROOT_CAUSE_IDENTIFIED or INSUFFICIENT_DATA.","jhkchan\u002Faws-agent-skills","jhkchan","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1083902?v=4","01M7A2SVQYP9GQTPTDXP5JKYQ4","Jacky Chan","01M7A2SVS117YWCTZABB75HZR1",4,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: ecr-push-pull-troubleshooter\ndescription: 'Diagnoses Amazon ECR push and pull failures through a fourteen-category diagnostic tree: authentication (docker login token expiry, IAM ecr:GetAuthorizationToken), repository policy vs IAM policy precedence, lifecycle policy prematurely deleting images, image size limit (10 GB), cross-region replication lag, KMS encryption key access denied, registry alias confusion (public vs private), scan-on-push findings blocking deployment, image tag immutability conflicts, docker manifest errors, pull-through cache misconfiguration, Fargate\u002FECS platform version vs image architecture mismatch (arm64 vs x86_64), layer download failures, and throttling. Walks symptoms to a verified root cause with evidence-backed probes; emits ROOT_CAUSE_IDENTIFIED or INSUFFICIENT_DATA.'\nlicense: Apache-2.0\ncompatibility: Agent runtime that reads SKILL.md (Claude Code, Cursor, Windsurf, Codex, Gemini). Offline symptom classification works from pasted docker \u002F aws ecr error output. Live-account diagnosis uses aws ecr\nmetadata:\n  domain: aws-cloudops\n  complexity: high\n  requires_llm: 'true'\n  phase: '2'\n  supports_pipeline: 'true'\n  entry_point: 'false'\n  family: DevTools\n  task_type: troubleshoot\n  skill_class: capability\n  lifecycle_status: active\n  verdict_shape: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA\n  when_to_use: 'Diagnosing an ECR push or pull failure (docker login \"denied: Your authorization token has expired\", docker push \"denied: User is not authorized\", image tag overwrite rejected, image'\n  when_not_to_use: Authoring a new lifecycle or repository policy from scratch (use ecr-repository-auditor), CI\u002FCD pipeline construction (use the codepipeline \u002F codebuild deployer skills), auditing image CVE\n  activation_triggers: ''\n  invocation_schema: '''Input: either (a) a symptom description (docker \u002F aws ecr error string, observed behaviour, \"push started failing after the role change\"), optionally paired with the registry \u002F repository'\n  invocation_example: '\"# Minimal valid input (offline symptom classification):\\nSymptom: \\\"docker push\\n  111111111111.dkr.ecr.us-east-1.amazonaws.com\u002Fapp:v1 returns\\\\n\\\\\\\"denied: Your authorization token has\\'\n  version: 0.1.0\n  author: Jacky Chan — AWS Community Builder\n  keywords: ECR, docker login, authorization token, ecr:GetAuthorizationToken, repository policy, lifecycle policy, tag immutability, image size limit, cross-region replication, KMS encryption, registry alias, public registry, scan on push, manifest, pull-through cache, Fargate architecture, arm64, x86_64, layer download, troubleshoot\n---\n\n# ECR Push\u002FPull Troubleshooter\n\n## Quick start\n\n- **Symptom → layer map (first plausible match drives the first probe):**\n  `Your authorization token has expired` \u002F `no basic auth credentials` →\n  AUTH_TOKEN_EXPIRED; `is not authorized to perform ecr:` → AUTH_IAM_DENIED\n  or POLICY_IAM \u002F POLICY_REPOSITORY; image gone after a policy run →\n  LIFECYCLE_DELETED; push rejected at > 10 GB → IMAGE_SIZE_EXCEEDED;\n  replica missing in the far region → REPLICATION_LAG; `KMS.AccessDeniedException`\n  on push → KMS_ACCESS_DENIED; pull from ECR Public when a private repo\n  was intended (or vice-versa) → REGISTRY_ALIAS_MISMATCH; deploy blocked\n  by scan finding → SCAN_BLOCKING; `cannot overwrite` \u002F `image is\n  immutable` → TAG_IMMUTABILITY; `manifest unknown` \u002F `no matching\n  manifest for platform` → MANIFEST_INVALID or ARCHITECTURE_MISMATCH;\n  upstream registry unreachable from pull-through cache → PULL_THROUGH_CACHE;\n  `Failed to register layer: layer not found` → LAYER_DOWNLOAD_FAILED.\n- **Always verify with a probe, never guess.** Each layer has a single\n  command that proves or disproves it. A ROOT_CAUSE_IDENTIFIED verdict\n  requires positive evidence — a failing probe that matches the symptom\n  — not a process of elimination.\n- **The ECR auth token is base64(username:password) and valid for 12\n  hours.** `aws ecr get-login-password` returns the password; `docker\n  login` wraps it as base64(`AWS`:`\u003Cpassword>`). A push that worked an\n  hour ago and now fails with `Your authorization token has expired` is\n  almost always a stale token. Re-run `aws ecr get-login-password |\n  docker login` and retry before investigating IAM.\n- **Repository policy and IAM policy are evaluated together — BOTH must\n  allow the action.** A same-account pull succeeds when the IAM principal\n  has the needed actions in IAM and no repository policy is attached\n  (no explicit deny). A cross-account pull requires BOTH the caller's\n  IAM policy AND the repository policy to allow the caller's account.\n  Adding only the IAM side is the most common cross-account ECR failure.\n- **Lifecycle policy rules evaluate in order; the FIRST matching rule\n  wins.** A rule \"count=1, untagged=true\" placed ABOVE a \"count=10,\n  tagged=true\" rule deletes the 11th image even if you expected the\n  tagged rule to protect it. Always read rule order, not just rules.\n- **Tag immutability is per-repository, not per-registry.** Enabling\n  `IMMUTABLE` on one repository does not affect any other. A push that\n  fails with `image tag already exists` fails only on repositories\n  configured as IMMUTABLE.\n\n## Mindset\nMindset reasoning moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n## Philosophy\nPhilosophy behaviours moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n## Quick reference — symptom triage table\n\n| Symptom phrase \u002F error | Most likely layer | First probe |\n|---|---|---|\n| `Your authorization token has expired`, `no basic auth credentials` | AUTH_TOKEN_EXPIRED | `aws ecr get-authorization-token` (decode base64, check `expiresAt`); inspect `~\u002F.docker\u002Fconfig.json` |\n| `denied: User arn:... is not authorized to perform: ecr:GetAuthorizationToken` | AUTH_IAM_DENIED | `iam simulate-principal-policy` with `ecr:GetAuthorizationToken` on `*` |\n| `denied: ... not authorized to perform: ecr:BatchCheckLayerAvailability` \u002F `BatchGetImage` \u002F `PutImage` | POLICY_IAM or POLICY_REPOSITORY | `get-repository-policy`, `iam simulate-principal-policy` on the repository ARN |\n| Image tag was present yesterday; now `manifest unknown` and gone from `describe-images` | LIFECYCLE_DELETED | `get-lifecycle-policy`, `describe-images` for last-pushed time |\n| Push fails with `Requested image size exceeds max size` | IMAGE_SIZE_EXCEEDED | `docker image inspect` Size; compare to 10 GiB compressed |\n| Replica missing in far region after a push | REPLICATION_LAG | `ecr describe-registry`, `ecr get-replication-configuration`, `describe-images --region \u003Cfar>` |\n| `KMS.AccessDeniedException` on push or pull | KMS_ACCESS_DENIED | `describe-registry` encryptionConfiguration; `kms describe-key`; simulate `kms:GenerateDataAccess` \u002F `kms:Decrypt` |\n| `manifest unknown` but only from some callers | REGISTRY_ALIAS_MISMATCH | Compare URI host (`public.ecr.aws` vs `\u003Caccount>.dkr.ecr.\u003Cregion>.amazonaws.com`); alias owner |\n| Deploy blocked; `describe-image-scan-findings` shows `HIGH`\u002F`CRITICAL` | SCAN_BLOCKING | `describe-image-scan-findings`; trace the consuming CD\u002FCodeDeploy gate |\n| `image tag already exists` \u002F `cannot be overwritten because the repository is immutable` | TAG_IMMUTABILITY | `describe-repositories` `imageTagMutability` for the repository |\n| `manifest unknown`, `no matching manifest for platform linux\u002Farm64` | MANIFEST_INVALID \u002F ARCHITECTURE_MISMATCH | `docker manifest inspect \u003Curi>`, `describe-images` imageManifest |\n| Pull-through cache: pull loops \u002F image never cached | PULL_THROUGH_CACHE | `describe-pull-through-cache-rules`, `describe-registry` |\n| `Failed to register layer: layer does not exist` \u002F `download failed after attempt=5` | LAYER_DOWNLOAD_FAILED | `batch-check-layer-availability`; retry on the failing region |\n| `ThrottlingException: Rate exceeded` on `BatchGetImage` | THROTTLED | ECR API throttle metrics; client-side retry |\n\n## Pre-flight: registry and gather-info gate\n\n### Account-wide pre-flight commands\nAccount-wide pre-flight command block moved to\n[references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\n\n### Repository-state short-circuit\nRepository-state short-circuit table moved to\n[references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the input is malformed (missing registry URI or repository name, no\nsymptom description, no caller context for cross-account diagnosis),\nemit:\n\nINSUFFICIENT_DATA re-prompt template for malformed\u002Fmissing input: [references\u002Fworked-examples.md](references\u002Fworked-examples.md).\n\n## Process — Diagnostic decision tree (apply in symptom order)\n\nThe tree is symptom-driven. Pick the entry point based on the observed\nsymptom, then walk the layer-specific probes in order. **Never emit\nROOT_CAUSE_IDENTIFIED without a failing probe that matches the symptom.**\n\n### Step 0: Non-obvious behaviours that change diagnosis\nStep 0 non-obvious behaviours moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n### Step 1: Symptom entry\n\n| Symptom | Branch |\n|---|---|\n| `Your authorization token has expired`, `no basic auth credentials` | Step 2 — Auth token |\n| `denied: ... is not authorized to perform: ecr:GetAuthorizationToken` | Step 3 — Auth IAM |\n| `denied: ... is not authorized to perform: ecr:BatchGetImage` \u002F `PutImage` \u002F etc. | Step 4 + Step 5 — IAM \u002F repository policy |\n| Image gone after a lifecycle policy run; `manifest unknown` recent | Step 6 — Lifecycle |\n| Push rejected with size limit | Step 7a — Image size |\n| Replica missing in the far region | Step 8 — Replication |\n| `KMS.AccessDeniedException` on push or pull | Step 9 — KMS |\n| `manifest unknown` only from some callers; pull from ECR Public when private was intended | Step 10 — Registry alias |\n| Deploy pipeline blocked; scan findings HIGH\u002FCRITICAL | Step 11 — Scan |\n| `image tag already exists`, `cannot be overwritten ... immutable` | Step 12 — Tag immutability |\n| `manifest unknown`, `no matching manifest for platform` | Step 13 — Manifest \u002F architecture |\n| Pull-through cache: pull loops, upstream unreachable | Step 14 — Pull-through cache |\n| `Failed to register layer: layer does not exist` | Step 15 — Layer download |\n\n### Step 2: AUTH_TOKEN_EXPIRED — docker login token expired\n\nSymptom: `Your authorization token has expired. Reauthenticate at ...`,\n`no basic auth credentials`, `error retrieving credentials`.\n\nProbe (token expiry via get-authorization-token, cached docker auth): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nThe decoded token's password contains an `X-amz-expires=43200` (12-hour)\nquery parameter. If `expiresAt` is in the past, the cached credentials\nare stale. If the token has expired, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: AUTH_TOKEN_EXPIRED`. Fix: refresh the token immediately before\nevery push; do not cache credentials across jobs.\n\n### Step 3: AUTH_IAM_DENIED — missing ecr:GetAuthorizationToken\n\nSymptom: `denied: ... is not authorized to perform:\necr:GetAuthorizationToken`. Without this permission, the caller cannot\nretrieve an auth token at all.\n\nProbe (simulate ecr:GetAuthorizationToken on `*`): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\n`ecr:GetAuthorizationToken` must be allowed on `*` (it is a\nservice-wide API, not per-resource). If the simulation returns\n`implicitDeny`, **ROOT_CAUSE_IDENTIFIED** with `LAYER: AUTH_IAM_DENIED`.\nFix: add `{\"Effect\": \"Allow\", \"Action\": \"ecr:GetAuthorizationToken\",\n\"Resource\": \"*\"}`.\n\n### Step 4: POLICY_IAM — IAM identity-based policy missing\n\nSymptom: `denied: ... is not authorized to perform:\necr:BatchCheckLayerAvailability` (or `BatchGetImage`, `PutImage`,\n`CompleteLayerUpload`, `InitiateLayerUpload`, `UploadLayerPart`,\n`GetDownloadUrlForLayer`).\n\nProbe (simulate push\u002Fpull ecr actions on the repository ARN): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nA **push** needs at minimum: `BatchCheckLayerAvailability`,\n`CompleteLayerUpload`, `InitiateLayerUpload`, `PutImage`,\n`UploadLayerPart`, plus `GetAuthorizationToken`. A **pull** needs at\nminimum: `BatchGetImage`, `GetDownloadUrlForLayer`, plus\n`GetAuthorizationToken`. If any required action returns `implicitDeny`,\n**ROOT_CAUSE_IDENTIFIED** with `LAYER: POLICY_IAM`. Add the missing\naction on the specific repository ARN.\n\n### Step 5: POLICY_REPOSITORY — repository policy missing (cross-account)\n\nSymptom: same-account access works; cross-account pull\u002Fpush is denied\neven though the caller's IAM policy allows it.\n\nProbe (get-repository-policy): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nSame-account callers do NOT need a repository policy — IAM alone is\nsufficient. Cross-account callers need BOTH the caller's IAM policy\nAND a repository policy statement listing the caller's account or ARN.\nIf the policy is empty or does not list the caller's\n`aws:PrincipalAccount`, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: POLICY_REPOSITORY`. Fix:\n\nFix command (set-repository-policy cross-account allow): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nAlways confirm before changing a resource-based policy — a too-broad\nprincipal can leak the repository.\n\n### Step 6: LIFECYCLE_DELETED — lifecycle policy deleted the image\n\nSymptom: image tag was present yesterday; today `manifest unknown` and\ngone from `describe-images`. The operator did not delete it manually.\n\nProbes (lifecycle policy, image list, CloudTrail BatchDeleteImage): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nLifecycle rules evaluate in order, first-match-wins. Look for a rule\nwith `type: expire` whose `selection` matches the missing image (e.g.,\n`count: 1, tagStatus: untagged` deletes any image that lost its last\ntag). If a rule's `lastEvaluatedAt` matches the disappearance window\nand the rule's `selection` matches, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: LIFECYCLE_DELETED`. Fix: reorder the rules (place `keep` above\n`expire`) or adjust `count` \u002F `tagStatus`.\n\n### Step 7: IMAGE_SIZE_EXCEEDED — image larger than 10 GB\n\nSymptom: push fails with `Requested image size exceeds max size limit`\nor LayerUpload fails on a single layer > 10 GB. ECR caps each\ncompressed layer at 10 GB and the overall compressed image at 10 GB.\n\n```bash\ndocker image inspect \u003Cimage>:\u003Ctag> --format '{{.Size}}'\n```\n\nDocker reports uncompressed size; the 10 GB cap is on compressed size.\nFor a rough check, compare docker's size to the threshold with a 1.5-2x\nmargin. If compressed image exceeds 10 GB, **ROOT_CAUSE_IDENTIFIED**\nwith `LAYER: IMAGE_SIZE_EXCEEDED`. Fix: multi-stage build, slimmer base\nimage, exclude dev dependencies, or split the image.\n\n### Step 8: REPLICATION_LAG — cross-region replication delay or misconfiguration\n\nSymptom: image pushed to source region; replica missing in destination\nregion. Pull in destination region fails with `manifest unknown`.\n\nProbes (describe-registry, replication configuration, destination-region images): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nReplication rules are per-source-registry. If no rule covers the\nrepository's region and destination, no replication occurs. If a rule\nexists, replication is asynchronous — typically seconds to minutes. If\nno rule covers the destination, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: REPLICATION_LAG`. If the rule exists but the image is missing\nminutes after push, check AWS Health for replication service degradation.\n\n### Step 9: KMS_ACCESS_DENIED — KMS encryption key access denied\n\nSymptom: `KMS.AccessDeniedException` on push or pull when the\nrepository uses `encryptionType: KMS`.\n\nProbes (encryption config, kms describe-key, simulate kms actions): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nThe pusher needs `kms:GenerateDataAccess`; the puller needs\n`kms:Decrypt`. The key policy must also grant the ECR service principal\naccess (typically `kms:CreateGrant` to `ecr.\u003Cregion>.amazonaws.com`).\nIf the simulation returns `implicitDeny`, **ROOT_CAUSE_IDENTIFIED**\nwith `LAYER: KMS_ACCESS_DENIED`. Fix: add the KMS permissions to the\ncaller's IAM policy AND verify the key policy grants ECR access.\n\n### Step 10: REGISTRY_ALIAS_MISMATCH — public vs private registry confusion\n\nSymptom: `manifest unknown` from some callers but not others; push\nappears to succeed but the image is in a different registry.\n\nProbe (ecr-public describe-registries alias ownership): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the URI host is `public.ecr.aws` but the operator intended a\nprivate registry (or vice-versa), or the public alias is owned by a\ndifferent account, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: REGISTRY_ALIAS_MISMATCH`. Fix: use the correct full URI and\nauthenticate to the correct registry.\n\n### Step 11: SCAN_BLOCKING — scan findings block deploy\n\nSymptom: docker push succeeds; the deploy pipeline refuses to promote\nthe image. The gate reads `describe-image-scan-findings` and blocks on\n`HIGH` \u002F `CRITICAL`.\n\nProbe (describe-image-scan-findings HIGH\u002FCRITICAL): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nECR does NOT block pushes based on scan findings — a downstream gate\n(CodeDeploy, a Lambda promotion step, a custom security gate) does the\nblocking. If scan findings are the blocker, **ROOT_CAUSE_IDENTIFIED**\nwith `LAYER: SCAN_BLOCKING`. Surface the findings; do NOT recommend\nbypassing without a security owner.\n\n### Step 12: TAG_IMMUTABILITY — image tag overwrite rejected\n\nSymptom: push fails with `image tag already exists and is immutable`.\n\nProbe (imageTagMutability check): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\n`IMMUTABLE` blocks overwrites on the named repository only —\nimmutability is per-repository, not per-registry. Fix: use a new tag\n(recommended for traceability) or switch to MUTABLE:\n\nFix command (put-image-tag-mutability MUTABLE): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the repository is `IMMUTABLE` and the push is an overwrite,\n**ROOT_CAUSE_IDENTIFIED** with `LAYER: TAG_IMMUTABILITY`.\n\n### Step 13: MANIFEST_INVALID \u002F ARCHITECTURE_MISMATCH — manifest and architecture issues\n\nSymptom: `manifest unknown`, `no matching manifest for platform\nlinux\u002Farm64 in the manifest list`, Fargate task stops with\n`CannotPullContainerError`.\n\nProbes (docker manifest inspect, batch-get-image manifest, Fargate\u002FLambda platform): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nManifest\u002Farchitecture pattern table: [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the manifest list does not include the requested platform or the\nimage is single-arch on the wrong host, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: ARCHITECTURE_MISMATCH` (preferred) or `LAYER: MANIFEST_INVALID`\nwhen the manifest is malformed.\n\n### Step 14: PULL_THROUGH_CACHE — pull-through cache misconfiguration\n\nSymptom: pull from a pull-through cache repository loops indefinitely;\nupstream registry unreachable; pull fails with `upstream repository\ndoes not exist`.\n\nProbe (describe-pull-through-cache-rules): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nPull-through-cache pattern table: [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the rule is misconfigured or the upstream is unreachable,\n**ROOT_CAUSE_IDENTIFIED** with `LAYER: PULL_THROUGH_CACHE`.\n\n### Step 15: LAYER_DOWNLOAD_FAILED — layer download failures\n\nSymptom: `failed to register layer: layer does not exist`,\n`download failed after attempt=5`, retryable errors during `docker\npull` for specific layers.\n\nProbe (batch-check-layer-availability): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nA layer returning `INVALID_LAYER_DIGEST` or missing from the registry\nis the smoking gun. Common causes: partial upload (pusher crashed\nmid-`CompleteLayerUpload`), lifecycle policy that deleted layers but\nnot the manifest, or a transient regional issue. If the layer is\nunavailable, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: LAYER_DOWNLOAD_FAILED`. Fix: re-push the image (the pusher\nuploads missing layers); if the cause is a service event, check AWS\nHealth.\n\n### Step 16: THROTTLED or INSUFFICIENT_DATA\n\nIf `ThrottlingException: Rate exceeded` appears on ECR APIs, route to\n`LAYER: THROTTLED` — the caller is hitting the ECR API throughput\nlimit. Recommend client-side retry with exponential backoff and\nrequest a Service Quotas increase for the specific API.\n\nIf none of the above produced a positive root-cause match, emit\n`VERDICT: INSUFFICIENT_DATA` with the missing probe listed.\n\n## Output format\n\n```text\nTARGET: \u003Cregistry-uri\u002Frepo:tag>\nVERDICT: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA\nREASON: \u003C1-2 sentences naming the failed layer and the failing probe>\nLAYER: \u003CAUTH_TOKEN_EXPIRED | AUTH_IAM_DENIED | POLICY_REPOSITORY |\n        POLICY_IAM | LIFECYCLE_DELETED | IMAGE_SIZE_EXCEEDED |\n        REPLICATION_LAG | KMS_ACCESS_DENIED | REGISTRY_ALIAS_MISMATCH |\n        SCAN_BLOCKING | TAG_IMMUTABILITY | MANIFEST_INVALID |\n        PULL_THROUGH_CACHE | ARCHITECTURE_MISMATCH |\n        LAYER_DOWNLOAD_FAILED | THROTTLED | UNKNOWN>\nEVIDENCE:\n  - \u003Cobserved symptom — error string or behaviour>\n  - \u003Cfailing probe — command and its output that confirms the cause>\n  - \u003Cpassing probes — layers ruled out>\nREMEDIATION:\n  1. \u003Cspecific action with CLI command>\n  2. \u003Cverification command after the fix>\nCONFIRM: Before executing any state-changing CLI, emit and await operator\n  approval: \"CONFIRM: About to \u003Caction> on \u003Crepo> in \u003Cregion>. Proceed?\n  (yes\u002Fno)\"\n```\n\n### Worked example — AUTH_TOKEN_EXPIRED in CI\n\n```text\nTARGET: 111111111111.dkr.ecr.us-east-1.amazonaws.com\u002Fapp:v1\nVERDICT: ROOT_CAUSE_IDENTIFIED\nREASON: CI cached an auth token whose 12-hour expiry elapsed 2 hours ago;\n  the cached entry points at a token issued 14 hours ago. The freshly\n  issued token returns expiresAt = +12 hours (Step 2).\nLAYER: AUTH_TOKEN_EXPIRED\nEVIDENCE:\n  - Symptom: docker push returns \"Your authorization token has expired\"\n    on every push from the CI runner.\n  - Probe: aws ecr get-authorization-token returned expiresAt =\n    \u003C14-hours-ago> for the cached token; the freshly-issued token\n    returns expiresAt = \u003C+12 hours>.\n  - Probe: cat ~\u002F.docker\u002Fconfig.json shows auths entry with the old token.\n  - Passing: iam simulate-principal-policy on the CI role returns allowed\n    for ecr:GetAuthorizationToken, ecr:PutImage, ecr:CompleteLayerUpload\n    (policy is not the issue).\nREMEDIATION:\n  1. aws ecr get-login-password --region us-east-1 --profile ci-profile | \\\n       docker login --username AWS --password-stdin \\\n       111111111111.dkr.ecr.us-east-1.amazonaws.com\n  2. Remove the cross-job cache for ~\u002F.docker\u002Fconfig.json.\n  3. Re-run the push; it should succeed in under a minute.\n```\n\n### Worked example — LIFECYCLE_DELETED\nFull worked example moved to\n[references\u002Fworked-examples.md](references\u002Fworked-examples.md).\n\n## Anti-Patterns — NEVER\n\n- NEVER declare ROOT_CAUSE_IDENTIFIED without a failing probe that\n  matches the symptom.\n- NEVER recommend refreshing the docker login token as the only fix\n  without checking the token's actual expiry via `expiresAt`. Guessing\n  \"must be expired\" misses IAM \u002F repository-policy causes.\n- NEVER assume a same-account pull needs a repository policy. The\n  default is IAM-only for same-account; adding a repository policy to\n  \"fix\" a same-account pull indicates the diagnosis went down the\n  wrong path.\n- NEVER assume a cross-account pull works with only the caller's IAM\n  policy. BOTH the IAM policy AND the repository's resource-based\n  policy must allow the action.\n- NEVER conclude a lifecycle policy \"didn't delete my image\" without\n  reading rule order — first-match-wins; a broad `expire` above a\n  narrow `keep` deletes what `keep` would have protected.\n- NEVER assume tag immutability is per-registry. It is per-repository.\n- NEVER chase KMS permissions for an `AES256`-encrypted repository.\n  Only `encryptionType: KMS` requires caller-side KMS permissions.\n- NEVER assume scan findings block the push. ECR accepts the image\n  regardless; a downstream gate does the blocking.\n- NEVER recommend disabling tag immutability without flagging the\n  traceability trade-off — MUTABLE lets a tag float, defeating\n  reproducibility.\n- NEVER assume `manifest unknown` means the image is missing. For\n  multi-arch images, it can mean the manifest list does not include\n  the requested platform.\n- NEVER recommend a Fargate platform version change without confirming\n  architecture — x86_64 vs arm64 is set on the task definition \u002F Lambda\n  config, not the platform version.\n- NEVER delete an ECR image tag that a Lambda function or ECS task\n  references. ECR does not track consumers; the tag breaks the next\n  cold start or task rollout.\n- NEVER conflate ECR Public with ECR Private. `public.ecr.aws` is a\n  globally public registry; `\u003Caccount>.dkr.ecr.\u003Cregion>.amazonaws.com`\n  is private. A login to one is not a login to the other.\n\n## Pre-flight safety checks (run before any state-changing CLI)\n\n- **MANDATORY CONFIRMATION GATE.** Before any state-changing operation\n  (`set-repository-policy`, `put-image-tag-mutability`,\n  `start-lifecycle-policy-preview`, `delete-repository`,\n  `put-replication-configuration`, `delete-pull-through-cache-rule`),\n  emit and await operator approval.\n- **Read-only first.** Every probe is read-only (`describe-*`, `get-*`,\n  `simulate-principal-policy`, `lookup-events`,\n  `batch-check-layer-availability`). Do not perform state-changing\n  operations as diagnostic probes.\n- **`set-repository-policy`** replaces the entire resource-based policy\n  — always read the current policy and merge; never overwrite. A\n  too-broad principal leak is a common security incident.\n- **`put-replication-configuration`** is regional and applies to the\n  whole source registry — confirm scope before applying.\n- **`delete-repository`** is irreversible and deletes every image —\n  confirm twice; consider a lifecycle retain-window first.\n- **Bulk remediation batch limit.** Batch into groups of at most 5\n  repositories, emit a single CONFIRM per batch, and verify between\n  batches.\n\n## Remediation guidance\n\nEach layer's fix is summarised below; the step sections above carry the\nfull probe commands and worked examples.\n\nPer-layer fix table moved to\n[references\u002Ferror-handling.md](references\u002Ferror-handling.md).\n\n## Recent AWS features (2024-2026)\nRecent AWS feature notes moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n\n## References (load on demand)\n\n- [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) — mindset, philosophy, Step 0 non-obvious behaviours, recent AWS features (moved from this file)\n- [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md) — account-wide pre-flight commands, repository-state short-circuit, and every step's probe, fix, and pattern-table commands (moved from this file)\n- [references\u002Fworked-examples.md](references\u002Fworked-examples.md) — LIFECYCLE_DELETED worked example and the INSUFFICIENT_DATA re-prompt template (moved from this file)\n- [references\u002Ferror-handling.md](references\u002Ferror-handling.md) — per-layer remediation fix table (moved from this file)\n- [references\u002Fecr-auth-and-policy-reference.md](references\u002Fecr-auth-and-policy-reference.md) — auth token mechanics, repository vs IAM policy evaluation\n- [references\u002Fecr-lifecycle-replication-reference.md](references\u002Fecr-lifecycle-replication-reference.md) — lifecycle policy evaluation and replication behaviour\n\n## Domain\n\nAWS CloudOps \u002F Container Registry Operations, Image Distribution,\nIdentity & Access Management for ECR, KMS Encryption for Registries,\nCross-Region Replication, and Container Architecture Compatibility.\n\n## AWS documentation\n\n- **Amazon ECR User Guide** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fwhat-is-ecr.html\n- **ECR private registry settings** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fregistry.html\n- **ECR repository policies** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Frepository-policies.html\n- **ECR lifecycle policies** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Flifecycle_policy_examples.html\n- **ECR image tag immutability** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fimage-tag-mutability.html\n- **ECR KMS encryption** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fencryption-at-rest.html\n- **ECR cross-region replication** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Freplication.html\n- **ECR pull-through cache** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fpull-through-cache.html\n- **ECR image scanning** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fimage-scanning.html\n- **ECR Public registry** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fpublic-registries.html\n","# ECR Push\u002FPull Troubleshooter\n\n## Quick start\n\n- **Symptom → layer map (first plausible match drives the first probe):**\n  `Your authorization token has expired` \u002F `no basic auth credentials` →\n  AUTH_TOKEN_EXPIRED; `is not authorized to perform ecr:` → AUTH_IAM_DENIED\n  or POLICY_IAM \u002F POLICY_REPOSITORY; image gone after a policy run →\n  LIFECYCLE_DELETED; push rejected at > 10 GB → IMAGE_SIZE_EXCEEDED;\n  replica missing in the far region → REPLICATION_LAG; `KMS.AccessDeniedException`\n  on push → KMS_ACCESS_DENIED; pull from ECR Public when a private repo\n  was intended (or vice-versa) → REGISTRY_ALIAS_MISMATCH; deploy blocked\n  by scan finding → SCAN_BLOCKING; `cannot overwrite` \u002F `image is\n  immutable` → TAG_IMMUTABILITY; `manifest unknown` \u002F `no matching\n  manifest for platform` → MANIFEST_INVALID or ARCHITECTURE_MISMATCH;\n  upstream registry unreachable from pull-through cache → PULL_THROUGH_CACHE;\n  `Failed to register layer: layer not found` → LAYER_DOWNLOAD_FAILED.\n- **Always verify with a probe, never guess.** Each layer has a single\n  command that proves or disproves it. A ROOT_CAUSE_IDENTIFIED verdict\n  requires positive evidence — a failing probe that matches the symptom\n  — not a process of elimination.\n- **The ECR auth token is base64(username:password) and valid for 12\n  hours.** `aws ecr get-login-password` returns the password; `docker\n  login` wraps it as base64(`AWS`:`\u003Cpassword>`). A push that worked an\n  hour ago and now fails with `Your authorization token has expired` is\n  almost always a stale token. Re-run `aws ecr get-login-password |\n  docker login` and retry before investigating IAM.\n- **Repository policy and IAM policy are evaluated together — BOTH must\n  allow the action.** A same-account pull succeeds when the IAM principal\n  has the needed actions in IAM and no repository policy is attached\n  (no explicit deny). A cross-account pull requires BOTH the caller's\n  IAM policy AND the repository policy to allow the caller's account.\n  Adding only the IAM side is the most common cross-account ECR failure.\n- **Lifecycle policy rules evaluate in order; the FIRST matching rule\n  wins.** A rule \"count=1, untagged=true\" placed ABOVE a \"count=10,\n  tagged=true\" rule deletes the 11th image even if you expected the\n  tagged rule to protect it. Always read rule order, not just rules.\n- **Tag immutability is per-repository, not per-registry.** Enabling\n  `IMMUTABLE` on one repository does not affect any other. A push that\n  fails with `image tag already exists` fails only on repositories\n  configured as IMMUTABLE.\n\n## Mindset\nMindset reasoning moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n## Philosophy\nPhilosophy behaviours moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n## Quick reference — symptom triage table\n\n| Symptom phrase \u002F error | Most likely layer | First probe |\n|---|---|---|\n| `Your authorization token has expired`, `no basic auth credentials` | AUTH_TOKEN_EXPIRED | `aws ecr get-authorization-token` (decode base64, check `expiresAt`); inspect `~\u002F.docker\u002Fconfig.json` |\n| `denied: User arn:... is not authorized to perform: ecr:GetAuthorizationToken` | AUTH_IAM_DENIED | `iam simulate-principal-policy` with `ecr:GetAuthorizationToken` on `*` |\n| `denied: ... not authorized to perform: ecr:BatchCheckLayerAvailability` \u002F `BatchGetImage` \u002F `PutImage` | POLICY_IAM or POLICY_REPOSITORY | `get-repository-policy`, `iam simulate-principal-policy` on the repository ARN |\n| Image tag was present yesterday; now `manifest unknown` and gone from `describe-images` | LIFECYCLE_DELETED | `get-lifecycle-policy`, `describe-images` for last-pushed time |\n| Push fails with `Requested image size exceeds max size` | IMAGE_SIZE_EXCEEDED | `docker image inspect` Size; compare to 10 GiB compressed |\n| Replica missing in far region after a push | REPLICATION_LAG | `ecr describe-registry`, `ecr get-replication-configuration`, `describe-images --region \u003Cfar>` |\n| `KMS.AccessDeniedException` on push or pull | KMS_ACCESS_DENIED | `describe-registry` encryptionConfiguration; `kms describe-key`; simulate `kms:GenerateDataAccess` \u002F `kms:Decrypt` |\n| `manifest unknown` but only from some callers | REGISTRY_ALIAS_MISMATCH | Compare URI host (`public.ecr.aws` vs `\u003Caccount>.dkr.ecr.\u003Cregion>.amazonaws.com`); alias owner |\n| Deploy blocked; `describe-image-scan-findings` shows `HIGH`\u002F`CRITICAL` | SCAN_BLOCKING | `describe-image-scan-findings`; trace the consuming CD\u002FCodeDeploy gate |\n| `image tag already exists` \u002F `cannot be overwritten because the repository is immutable` | TAG_IMMUTABILITY | `describe-repositories` `imageTagMutability` for the repository |\n| `manifest unknown`, `no matching manifest for platform linux\u002Farm64` | MANIFEST_INVALID \u002F ARCHITECTURE_MISMATCH | `docker manifest inspect \u003Curi>`, `describe-images` imageManifest |\n| Pull-through cache: pull loops \u002F image never cached | PULL_THROUGH_CACHE | `describe-pull-through-cache-rules`, `describe-registry` |\n| `Failed to register layer: layer does not exist` \u002F `download failed after attempt=5` | LAYER_DOWNLOAD_FAILED | `batch-check-layer-availability`; retry on the failing region |\n| `ThrottlingException: Rate exceeded` on `BatchGetImage` | THROTTLED | ECR API throttle metrics; client-side retry |\n\n## Pre-flight: registry and gather-info gate\n\n### Account-wide pre-flight commands\nAccount-wide pre-flight command block moved to\n[references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\n\n### Repository-state short-circuit\nRepository-state short-circuit table moved to\n[references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the input is malformed (missing registry URI or repository name, no\nsymptom description, no caller context for cross-account diagnosis),\nemit:\n\nINSUFFICIENT_DATA re-prompt template for malformed\u002Fmissing input: [references\u002Fworked-examples.md](references\u002Fworked-examples.md).\n\n## Process — Diagnostic decision tree (apply in symptom order)\n\nThe tree is symptom-driven. Pick the entry point based on the observed\nsymptom, then walk the layer-specific probes in order. **Never emit\nROOT_CAUSE_IDENTIFIED without a failing probe that matches the symptom.**\n\n### Step 0: Non-obvious behaviours that change diagnosis\nStep 0 non-obvious behaviours moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n### Step 1: Symptom entry\n\n| Symptom | Branch |\n|---|---|\n| `Your authorization token has expired`, `no basic auth credentials` | Step 2 — Auth token |\n| `denied: ... is not authorized to perform: ecr:GetAuthorizationToken` | Step 3 — Auth IAM |\n| `denied: ... is not authorized to perform: ecr:BatchGetImage` \u002F `PutImage` \u002F etc. | Step 4 + Step 5 — IAM \u002F repository policy |\n| Image gone after a lifecycle policy run; `manifest unknown` recent | Step 6 — Lifecycle |\n| Push rejected with size limit | Step 7a — Image size |\n| Replica missing in the far region | Step 8 — Replication |\n| `KMS.AccessDeniedException` on push or pull | Step 9 — KMS |\n| `manifest unknown` only from some callers; pull from ECR Public when private was intended | Step 10 — Registry alias |\n| Deploy pipeline blocked; scan findings HIGH\u002FCRITICAL | Step 11 — Scan |\n| `image tag already exists`, `cannot be overwritten ... immutable` | Step 12 — Tag immutability |\n| `manifest unknown`, `no matching manifest for platform` | Step 13 — Manifest \u002F architecture |\n| Pull-through cache: pull loops, upstream unreachable | Step 14 — Pull-through cache |\n| `Failed to register layer: layer does not exist` | Step 15 — Layer download |\n\n### Step 2: AUTH_TOKEN_EXPIRED — docker login token expired\n\nSymptom: `Your authorization token has expired. Reauthenticate at ...`,\n`no basic auth credentials`, `error retrieving credentials`.\n\nProbe (token expiry via get-authorization-token, cached docker auth): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nThe decoded token's password contains an `X-amz-expires=43200` (12-hour)\nquery parameter. If `expiresAt` is in the past, the cached credentials\nare stale. If the token has expired, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: AUTH_TOKEN_EXPIRED`. Fix: refresh the token immediately before\nevery push; do not cache credentials across jobs.\n\n### Step 3: AUTH_IAM_DENIED — missing ecr:GetAuthorizationToken\n\nSymptom: `denied: ... is not authorized to perform:\necr:GetAuthorizationToken`. Without this permission, the caller cannot\nretrieve an auth token at all.\n\nProbe (simulate ecr:GetAuthorizationToken on `*`): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\n`ecr:GetAuthorizationToken` must be allowed on `*` (it is a\nservice-wide API, not per-resource). If the simulation returns\n`implicitDeny`, **ROOT_CAUSE_IDENTIFIED** with `LAYER: AUTH_IAM_DENIED`.\nFix: add `{\"Effect\": \"Allow\", \"Action\": \"ecr:GetAuthorizationToken\",\n\"Resource\": \"*\"}`.\n\n### Step 4: POLICY_IAM — IAM identity-based policy missing\n\nSymptom: `denied: ... is not authorized to perform:\necr:BatchCheckLayerAvailability` (or `BatchGetImage`, `PutImage`,\n`CompleteLayerUpload`, `InitiateLayerUpload`, `UploadLayerPart`,\n`GetDownloadUrlForLayer`).\n\nProbe (simulate push\u002Fpull ecr actions on the repository ARN): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nA **push** needs at minimum: `BatchCheckLayerAvailability`,\n`CompleteLayerUpload`, `InitiateLayerUpload`, `PutImage`,\n`UploadLayerPart`, plus `GetAuthorizationToken`. A **pull** needs at\nminimum: `BatchGetImage`, `GetDownloadUrlForLayer`, plus\n`GetAuthorizationToken`. If any required action returns `implicitDeny`,\n**ROOT_CAUSE_IDENTIFIED** with `LAYER: POLICY_IAM`. Add the missing\naction on the specific repository ARN.\n\n### Step 5: POLICY_REPOSITORY — repository policy missing (cross-account)\n\nSymptom: same-account access works; cross-account pull\u002Fpush is denied\neven though the caller's IAM policy allows it.\n\nProbe (get-repository-policy): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nSame-account callers do NOT need a repository policy — IAM alone is\nsufficient. Cross-account callers need BOTH the caller's IAM policy\nAND a repository policy statement listing the caller's account or ARN.\nIf the policy is empty or does not list the caller's\n`aws:PrincipalAccount`, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: POLICY_REPOSITORY`. Fix:\n\nFix command (set-repository-policy cross-account allow): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nAlways confirm before changing a resource-based policy — a too-broad\nprincipal can leak the repository.\n\n### Step 6: LIFECYCLE_DELETED — lifecycle policy deleted the image\n\nSymptom: image tag was present yesterday; today `manifest unknown` and\ngone from `describe-images`. The operator did not delete it manually.\n\nProbes (lifecycle policy, image list, CloudTrail BatchDeleteImage): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nLifecycle rules evaluate in order, first-match-wins. Look for a rule\nwith `type: expire` whose `selection` matches the missing image (e.g.,\n`count: 1, tagStatus: untagged` deletes any image that lost its last\ntag). If a rule's `lastEvaluatedAt` matches the disappearance window\nand the rule's `selection` matches, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: LIFECYCLE_DELETED`. Fix: reorder the rules (place `keep` above\n`expire`) or adjust `count` \u002F `tagStatus`.\n\n### Step 7: IMAGE_SIZE_EXCEEDED — image larger than 10 GB\n\nSymptom: push fails with `Requested image size exceeds max size limit`\nor LayerUpload fails on a single layer > 10 GB. ECR caps each\ncompressed layer at 10 GB and the overall compressed image at 10 GB.\n\n```bash\ndocker image inspect \u003Cimage>:\u003Ctag> --format '{{.Size}}'\n```\n\nDocker reports uncompressed size; the 10 GB cap is on compressed size.\nFor a rough check, compare docker's size to the threshold with a 1.5-2x\nmargin. If compressed image exceeds 10 GB, **ROOT_CAUSE_IDENTIFIED**\nwith `LAYER: IMAGE_SIZE_EXCEEDED`. Fix: multi-stage build, slimmer base\nimage, exclude dev dependencies, or split the image.\n\n### Step 8: REPLICATION_LAG — cross-region replication delay or misconfiguration\n\nSymptom: image pushed to source region; replica missing in destination\nregion. Pull in destination region fails with `manifest unknown`.\n\nProbes (describe-registry, replication configuration, destination-region images): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nReplication rules are per-source-registry. If no rule covers the\nrepository's region and destination, no replication occurs. If a rule\nexists, replication is asynchronous — typically seconds to minutes. If\nno rule covers the destination, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: REPLICATION_LAG`. If the rule exists but the image is missing\nminutes after push, check AWS Health for replication service degradation.\n\n### Step 9: KMS_ACCESS_DENIED — KMS encryption key access denied\n\nSymptom: `KMS.AccessDeniedException` on push or pull when the\nrepository uses `encryptionType: KMS`.\n\nProbes (encryption config, kms describe-key, simulate kms actions): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nThe pusher needs `kms:GenerateDataAccess`; the puller needs\n`kms:Decrypt`. The key policy must also grant the ECR service principal\naccess (typically `kms:CreateGrant` to `ecr.\u003Cregion>.amazonaws.com`).\nIf the simulation returns `implicitDeny`, **ROOT_CAUSE_IDENTIFIED**\nwith `LAYER: KMS_ACCESS_DENIED`. Fix: add the KMS permissions to the\ncaller's IAM policy AND verify the key policy grants ECR access.\n\n### Step 10: REGISTRY_ALIAS_MISMATCH — public vs private registry confusion\n\nSymptom: `manifest unknown` from some callers but not others; push\nappears to succeed but the image is in a different registry.\n\nProbe (ecr-public describe-registries alias ownership): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the URI host is `public.ecr.aws` but the operator intended a\nprivate registry (or vice-versa), or the public alias is owned by a\ndifferent account, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: REGISTRY_ALIAS_MISMATCH`. Fix: use the correct full URI and\nauthenticate to the correct registry.\n\n### Step 11: SCAN_BLOCKING — scan findings block deploy\n\nSymptom: docker push succeeds; the deploy pipeline refuses to promote\nthe image. The gate reads `describe-image-scan-findings` and blocks on\n`HIGH` \u002F `CRITICAL`.\n\nProbe (describe-image-scan-findings HIGH\u002FCRITICAL): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nECR does NOT block pushes based on scan findings — a downstream gate\n(CodeDeploy, a Lambda promotion step, a custom security gate) does the\nblocking. If scan findings are the blocker, **ROOT_CAUSE_IDENTIFIED**\nwith `LAYER: SCAN_BLOCKING`. Surface the findings; do NOT recommend\nbypassing without a security owner.\n\n### Step 12: TAG_IMMUTABILITY — image tag overwrite rejected\n\nSymptom: push fails with `image tag already exists and is immutable`.\n\nProbe (imageTagMutability check): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\n`IMMUTABLE` blocks overwrites on the named repository only —\nimmutability is per-repository, not per-registry. Fix: use a new tag\n(recommended for traceability) or switch to MUTABLE:\n\nFix command (put-image-tag-mutability MUTABLE): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the repository is `IMMUTABLE` and the push is an overwrite,\n**ROOT_CAUSE_IDENTIFIED** with `LAYER: TAG_IMMUTABILITY`.\n\n### Step 13: MANIFEST_INVALID \u002F ARCHITECTURE_MISMATCH — manifest and architecture issues\n\nSymptom: `manifest unknown`, `no matching manifest for platform\nlinux\u002Farm64 in the manifest list`, Fargate task stops with\n`CannotPullContainerError`.\n\nProbes (docker manifest inspect, batch-get-image manifest, Fargate\u002FLambda platform): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nManifest\u002Farchitecture pattern table: [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the manifest list does not include the requested platform or the\nimage is single-arch on the wrong host, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: ARCHITECTURE_MISMATCH` (preferred) or `LAYER: MANIFEST_INVALID`\nwhen the manifest is malformed.\n\n### Step 14: PULL_THROUGH_CACHE — pull-through cache misconfiguration\n\nSymptom: pull from a pull-through cache repository loops indefinitely;\nupstream registry unreachable; pull fails with `upstream repository\ndoes not exist`.\n\nProbe (describe-pull-through-cache-rules): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nPull-through-cache pattern table: [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nIf the rule is misconfigured or the upstream is unreachable,\n**ROOT_CAUSE_IDENTIFIED** with `LAYER: PULL_THROUGH_CACHE`.\n\n### Step 15: LAYER_DOWNLOAD_FAILED — layer download failures\n\nSymptom: `failed to register layer: layer does not exist`,\n`download failed after attempt=5`, retryable errors during `docker\npull` for specific layers.\n\nProbe (batch-check-layer-availability): [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md).\n\nA layer returning `INVALID_LAYER_DIGEST` or missing from the registry\nis the smoking gun. Common causes: partial upload (pusher crashed\nmid-`CompleteLayerUpload`), lifecycle policy that deleted layers but\nnot the manifest, or a transient regional issue. If the layer is\nunavailable, **ROOT_CAUSE_IDENTIFIED** with\n`LAYER: LAYER_DOWNLOAD_FAILED`. Fix: re-push the image (the pusher\nuploads missing layers); if the cause is a service event, check AWS\nHealth.\n\n### Step 16: THROTTLED or INSUFFICIENT_DATA\n\nIf `ThrottlingException: Rate exceeded` appears on ECR APIs, route to\n`LAYER: THROTTLED` — the caller is hitting the ECR API throughput\nlimit. Recommend client-side retry with exponential backoff and\nrequest a Service Quotas increase for the specific API.\n\nIf none of the above produced a positive root-cause match, emit\n`VERDICT: INSUFFICIENT_DATA` with the missing probe listed.\n\n## Output format\n\n```text\nTARGET: \u003Cregistry-uri\u002Frepo:tag>\nVERDICT: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA\nREASON: \u003C1-2 sentences naming the failed layer and the failing probe>\nLAYER: \u003CAUTH_TOKEN_EXPIRED | AUTH_IAM_DENIED | POLICY_REPOSITORY |\n        POLICY_IAM | LIFECYCLE_DELETED | IMAGE_SIZE_EXCEEDED |\n        REPLICATION_LAG | KMS_ACCESS_DENIED | REGISTRY_ALIAS_MISMATCH |\n        SCAN_BLOCKING | TAG_IMMUTABILITY | MANIFEST_INVALID |\n        PULL_THROUGH_CACHE | ARCHITECTURE_MISMATCH |\n        LAYER_DOWNLOAD_FAILED | THROTTLED | UNKNOWN>\nEVIDENCE:\n  - \u003Cobserved symptom — error string or behaviour>\n  - \u003Cfailing probe — command and its output that confirms the cause>\n  - \u003Cpassing probes — layers ruled out>\nREMEDIATION:\n  1. \u003Cspecific action with CLI command>\n  2. \u003Cverification command after the fix>\nCONFIRM: Before executing any state-changing CLI, emit and await operator\n  approval: \"CONFIRM: About to \u003Caction> on \u003Crepo> in \u003Cregion>. Proceed?\n  (yes\u002Fno)\"\n```\n\n### Worked example — AUTH_TOKEN_EXPIRED in CI\n\n```text\nTARGET: 111111111111.dkr.ecr.us-east-1.amazonaws.com\u002Fapp:v1\nVERDICT: ROOT_CAUSE_IDENTIFIED\nREASON: CI cached an auth token whose 12-hour expiry elapsed 2 hours ago;\n  the cached entry points at a token issued 14 hours ago. The freshly\n  issued token returns expiresAt = +12 hours (Step 2).\nLAYER: AUTH_TOKEN_EXPIRED\nEVIDENCE:\n  - Symptom: docker push returns \"Your authorization token has expired\"\n    on every push from the CI runner.\n  - Probe: aws ecr get-authorization-token returned expiresAt =\n    \u003C14-hours-ago> for the cached token; the freshly-issued token\n    returns expiresAt = \u003C+12 hours>.\n  - Probe: cat ~\u002F.docker\u002Fconfig.json shows auths entry with the old token.\n  - Passing: iam simulate-principal-policy on the CI role returns allowed\n    for ecr:GetAuthorizationToken, ecr:PutImage, ecr:CompleteLayerUpload\n    (policy is not the issue).\nREMEDIATION:\n  1. aws ecr get-login-password --region us-east-1 --profile ci-profile | \\\n       docker login --username AWS --password-stdin \\\n       111111111111.dkr.ecr.us-east-1.amazonaws.com\n  2. Remove the cross-job cache for ~\u002F.docker\u002Fconfig.json.\n  3. Re-run the push; it should succeed in under a minute.\n```\n\n### Worked example — LIFECYCLE_DELETED\nFull worked example moved to\n[references\u002Fworked-examples.md](references\u002Fworked-examples.md).\n\n## Anti-Patterns — NEVER\n\n- NEVER declare ROOT_CAUSE_IDENTIFIED without a failing probe that\n  matches the symptom.\n- NEVER recommend refreshing the docker login token as the only fix\n  without checking the token's actual expiry via `expiresAt`. Guessing\n  \"must be expired\" misses IAM \u002F repository-policy causes.\n- NEVER assume a same-account pull needs a repository policy. The\n  default is IAM-only for same-account; adding a repository policy to\n  \"fix\" a same-account pull indicates the diagnosis went down the\n  wrong path.\n- NEVER assume a cross-account pull works with only the caller's IAM\n  policy. BOTH the IAM policy AND the repository's resource-based\n  policy must allow the action.\n- NEVER conclude a lifecycle policy \"didn't delete my image\" without\n  reading rule order — first-match-wins; a broad `expire` above a\n  narrow `keep` deletes what `keep` would have protected.\n- NEVER assume tag immutability is per-registry. It is per-repository.\n- NEVER chase KMS permissions for an `AES256`-encrypted repository.\n  Only `encryptionType: KMS` requires caller-side KMS permissions.\n- NEVER assume scan findings block the push. ECR accepts the image\n  regardless; a downstream gate does the blocking.\n- NEVER recommend disabling tag immutability without flagging the\n  traceability trade-off — MUTABLE lets a tag float, defeating\n  reproducibility.\n- NEVER assume `manifest unknown` means the image is missing. For\n  multi-arch images, it can mean the manifest list does not include\n  the requested platform.\n- NEVER recommend a Fargate platform version change without confirming\n  architecture — x86_64 vs arm64 is set on the task definition \u002F Lambda\n  config, not the platform version.\n- NEVER delete an ECR image tag that a Lambda function or ECS task\n  references. ECR does not track consumers; the tag breaks the next\n  cold start or task rollout.\n- NEVER conflate ECR Public with ECR Private. `public.ecr.aws` is a\n  globally public registry; `\u003Caccount>.dkr.ecr.\u003Cregion>.amazonaws.com`\n  is private. A login to one is not a login to the other.\n\n## Pre-flight safety checks (run before any state-changing CLI)\n\n- **MANDATORY CONFIRMATION GATE.** Before any state-changing operation\n  (`set-repository-policy`, `put-image-tag-mutability`,\n  `start-lifecycle-policy-preview`, `delete-repository`,\n  `put-replication-configuration`, `delete-pull-through-cache-rule`),\n  emit and await operator approval.\n- **Read-only first.** Every probe is read-only (`describe-*`, `get-*`,\n  `simulate-principal-policy`, `lookup-events`,\n  `batch-check-layer-availability`). Do not perform state-changing\n  operations as diagnostic probes.\n- **`set-repository-policy`** replaces the entire resource-based policy\n  — always read the current policy and merge; never overwrite. A\n  too-broad principal leak is a common security incident.\n- **`put-replication-configuration`** is regional and applies to the\n  whole source registry — confirm scope before applying.\n- **`delete-repository`** is irreversible and deletes every image —\n  confirm twice; consider a lifecycle retain-window first.\n- **Bulk remediation batch limit.** Batch into groups of at most 5\n  repositories, emit a single CONFIRM per batch, and verify between\n  batches.\n\n## Remediation guidance\n\nEach layer's fix is summarised below; the step sections above carry the\nfull probe commands and worked examples.\n\nPer-layer fix table moved to\n[references\u002Ferror-handling.md](references\u002Ferror-handling.md).\n\n## Recent AWS features (2024-2026)\nRecent AWS feature notes moved to\n[references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md).\n\n\n## References (load on demand)\n\n- [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) — mindset, philosophy, Step 0 non-obvious behaviours, recent AWS features (moved from this file)\n- [references\u002Fdiagnostic-commands.md](references\u002Fdiagnostic-commands.md) — account-wide pre-flight commands, repository-state short-circuit, and every step's probe, fix, and pattern-table commands (moved from this file)\n- [references\u002Fworked-examples.md](references\u002Fworked-examples.md) — LIFECYCLE_DELETED worked example and the INSUFFICIENT_DATA re-prompt template (moved from this file)\n- [references\u002Ferror-handling.md](references\u002Ferror-handling.md) — per-layer remediation fix table (moved from this file)\n- [references\u002Fecr-auth-and-policy-reference.md](references\u002Fecr-auth-and-policy-reference.md) — auth token mechanics, repository vs IAM policy evaluation\n- [references\u002Fecr-lifecycle-replication-reference.md](references\u002Fecr-lifecycle-replication-reference.md) — lifecycle policy evaluation and replication behaviour\n\n## Domain\n\nAWS CloudOps \u002F Container Registry Operations, Image Distribution,\nIdentity & Access Management for ECR, KMS Encryption for Registries,\nCross-Region Replication, and Container Architecture Compatibility.\n\n## AWS documentation\n\n- **Amazon ECR User Guide** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fwhat-is-ecr.html\n- **ECR private registry settings** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fregistry.html\n- **ECR repository policies** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Frepository-policies.html\n- **ECR lifecycle policies** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Flifecycle_policy_examples.html\n- **ECR image tag immutability** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fimage-tag-mutability.html\n- **ECR KMS encryption** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fencryption-at-rest.html\n- **ECR cross-region replication** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Freplication.html\n- **ECR pull-through cache** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fpull-through-cache.html\n- **ECR image scanning** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fimage-scanning.html\n- **ECR Public registry** — https:\u002F\u002Fdocs.aws.amazon.com\u002FAmazonECR\u002Flatest\u002Fuserguide\u002Fpublic-registries.html\n",{"name":5,"license":15,"metadata":24,"description":7,"compatibility":43},{"phase":25,"author":26,"domain":27,"family":28,"version":29,"keywords":30,"task_type":31,"complexity":32,"entry_point":33,"skill_class":34,"when_to_use":35,"requires_llm":36,"verdict_shape":37,"when_not_to_use":38,"lifecycle_status":39,"invocation_schema":40,"supports_pipeline":36,"invocation_example":41,"activation_triggers":42},"2","Jacky Chan — AWS Community Builder","aws-cloudops","DevTools","0.1.0","ECR, docker login, authorization token, ecr:GetAuthorizationToken, repository policy, lifecycle policy, tag immutability, image size limit, cross-region replication, KMS encryption, registry alias, public registry, scan on push, manifest, pull-through cache, Fargate architecture, arm64, x86_64, layer download, troubleshoot","troubleshoot","high","false","capability","Diagnosing an ECR push or pull failure (docker login \"denied: Your authorization token has expired\", docker push \"denied: User is not authorized\", image tag overwrite rejected, image","true","ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA","Authoring a new lifecycle or repository policy from scratch (use ecr-repository-auditor), CI\u002FCD pipeline construction (use the codepipeline \u002F codebuild deployer skills), auditing image CVE","active","'Input: either (a) a symptom description (docker \u002F aws ecr error string, observed behaviour, \"push started failing after the role change\"), optionally paired with the registry \u002F repository","\"# Minimal valid input (offline symptom classification):\\nSymptom: \\\"docker push\\n  111111111111.dkr.ecr.us-east-1.amazonaws.com\u002Fapp:v1 returns\\\\n\\\\\\\"denied: Your authorization token has\\","","Agent runtime that reads SKILL.md (Claude Code, Cursor, Windsurf, Codex, Gemini). Offline symptom classification works from pasted docker \u002F aws ecr error output. Live-account diagnosis uses aws ecr","main","eeace51bd5dd1db2030729d83eeab988861553aa","skills\u002Fecr-push-pull-troubleshooter",0,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills","https:\u002F\u002Fgithub.com\u002Fjhkchan","CTO & Co-Founder @Beever-AI  & @votee. CAISP. AWS Community Builder. Organizer@GDGCloudHK. MongoDB Champion. Technopreneur + Infornographer.","2026-09-24 08:54:10",{"source":8,"skillName":5,"commands":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add jhkchan\u002Faws-agent-skills --skill ecr-push-pull-troubleshooter",{"tool":58,"command":59},"bunx","bunx skills add jhkchan\u002Faws-agent-skills --skill ecr-push-pull-troubleshooter",{"tool":61,"command":62},"pnpm","pnpm dlx skills add jhkchan\u002Faws-agent-skills --skill ecr-push-pull-troubleshooter","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002FSKILL.md",true,[66,72,76,80,84,88,92,96,100,104,108,112,116,120,124,128,132,136,140,144,148],{"path":67,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":70,"sourceHtmlUrl":71},"eval\u002Ftest-cases.yaml","REFERENCE","参考文档",11922,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Feval\u002Ftest-cases.yaml",{"path":73,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":74,"sourceHtmlUrl":75},"evals\u002Fbaselines\u002Fauth-token-expired-ci-cache.md",469,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fbaselines\u002Fauth-token-expired-ci-cache.md",{"path":77,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":78,"sourceHtmlUrl":79},"evals\u002Fbaselines\u002Fcross-account-repo-policy-missing.md",460,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fbaselines\u002Fcross-account-repo-policy-missing.md",{"path":81,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":82,"sourceHtmlUrl":83},"evals\u002Fbaselines\u002Ffargate-arm64-arch-mismatch.md",499,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fbaselines\u002Ffargate-arm64-arch-mismatch.md",{"path":85,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":86,"sourceHtmlUrl":87},"evals\u002Fbaselines\u002Flifecycle-policy-first-match-delete.md",437,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fbaselines\u002Flifecycle-policy-first-match-delete.md",{"path":89,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":90,"sourceHtmlUrl":91},"evals\u002Fbaselines\u002Ftag-immutability-overwrite-blocked.md",446,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fbaselines\u002Ftag-immutability-overwrite-blocked.md",{"path":93,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":94,"sourceHtmlUrl":95},"evals\u002Feval_config.yaml",2073,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Feval_config.yaml",{"path":97,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":98,"sourceHtmlUrl":99},"evals\u002Fevals.json",5189,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fevals.json",{"path":101,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":102,"sourceHtmlUrl":103},"evals\u002Fprompts\u002Fauth-token-expired-ci-cache.md",1673,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fprompts\u002Fauth-token-expired-ci-cache.md",{"path":105,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":106,"sourceHtmlUrl":107},"evals\u002Fprompts\u002Fcross-account-repo-policy-missing.md",1796,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fprompts\u002Fcross-account-repo-policy-missing.md",{"path":109,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":110,"sourceHtmlUrl":111},"evals\u002Fprompts\u002Ffargate-arm64-arch-mismatch.md",1757,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fprompts\u002Ffargate-arm64-arch-mismatch.md",{"path":113,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":114,"sourceHtmlUrl":115},"evals\u002Fprompts\u002Flifecycle-policy-first-match-delete.md",1922,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fprompts\u002Flifecycle-policy-first-match-delete.md",{"path":117,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":118,"sourceHtmlUrl":119},"evals\u002Fprompts\u002Ftag-immutability-overwrite-blocked.md",1420,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fevals\u002Fprompts\u002Ftag-immutability-overwrite-blocked.md",{"path":121,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":122,"sourceHtmlUrl":123},"examples\u002FREADME.md",6517,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fexamples\u002FREADME.md",{"path":125,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":126,"sourceHtmlUrl":127},"references\u002Fadvanced-patterns.md",6509,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Freferences\u002Fadvanced-patterns.md",{"path":129,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":130,"sourceHtmlUrl":131},"references\u002Fdiagnostic-commands.md",8843,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Freferences\u002Fdiagnostic-commands.md",{"path":133,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":134,"sourceHtmlUrl":135},"references\u002Fecr-auth-and-policy-reference.md",7216,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Freferences\u002Fecr-auth-and-policy-reference.md",{"path":137,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":138,"sourceHtmlUrl":139},"references\u002Fecr-lifecycle-replication-reference.md",8668,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Freferences\u002Fecr-lifecycle-replication-reference.md",{"path":141,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":142,"sourceHtmlUrl":143},"references\u002Ferror-handling.md",3320,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Freferences\u002Ferror-handling.md",{"path":145,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":146,"sourceHtmlUrl":147},"references\u002Fworked-examples.md",1919,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Freferences\u002Fworked-examples.md",{"path":149,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":150,"sourceHtmlUrl":151},"skill.usf.yaml",4646,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fecr-push-pull-troubleshooter\u002Fskill.usf.yaml",[153,160,167,174,181,188],{"skillNo":154,"name":155,"nameZh":6,"description":156,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":157,"categories":158,"keywords":159,"publishedAt":19},"01M7ADVD60X4PCAPKSE58P9NDC","xray-tracing-deployer","Deploys AWS X-Ray distributed tracing with production-grade configuration: X-Ray daemon deployment (EC2 systemd, ECS sidecar, EKS DaemonSet, Lambda built-in), SDK instrumentation (Java, Python, Node.js, Go, .NET) with annotations and metadata, sampling rules (default reservoir + rate vs custom rules with URL \u002F method \u002F service-name predicates), service map generation, trace query and retrieval, groups and insights, CloudWatch ServiceLens integration, IAM permissions (PutTraceSegments, GetSamplingRules), and latest features (Lambda Powertools tracing, OpenTelemetry \u002F ADOT Collector support, W3C trace context). Emits a READY_TO_DEPLOY checklist with every configuration item verified. Use when enabling X-Ray on a new application, adding tracing to ECS \u002F EKS \u002F Lambda, validating a sampling configuration, or generating daemon deployment CLI and IaC templates. Triggers: X-Ray, distributed tracing, X-Ray daemon, sampling rules, service map, X-Ray SDK, OpenTelemetry, ADOT, Lambda Powertools, CloudWatch ServiceLens.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxray-tracing-deployer\u002FSKILL.md",[],[],{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":166,"publishedAt":19},"01M7ADTVJ7DCBM9CB1FY51GH7J","wellarchitected-workload-auditor","Audits AWS Well-Architected Tool workloads for review staleness, per-pillar high-risk issue counts, milestone tracking gaps, and remediation plan completeness. Emits a deterministic verdict (STALE_REVIEW | HIGH_RISK | CONFIG_GAP | OK) per workload with per-pillar risk breakdown, milestone trend analysis, and specific remediation. Use when reviewing Well-Architected workloads, checking WA review freshness, auditing high-risk issues per pillar, validating milestone coverage, or tracking remediation plans.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwellarchitected-workload-auditor\u002FSKILL.md",[],[],{"skillNo":168,"name":169,"nameZh":6,"description":170,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":171,"categories":172,"keywords":173,"publishedAt":19},"01M7ADT59G6FTTNZYHT2QRPNNP","wellarchitected-review-operator","Operates AWS Well-Architected Tool reviews end-to-end — creates workloads, runs pillar reviews (operational excellence, security, reliability, performance, cost optimization, sustainability, Prosperity), answers questions with risk-tier rationale, generates reports and improvement plans, creates milestones, and integrates with Trusted Advisor and Well-Architected Labs. Runs deterministic pre-checks (workload existence, lens availability, pillar coverage), emits the exact update-answer \u002F get-consolidated-report CLI behind a CONFIRM gate, and verifies risk-tier transitions. Emits READY | BLOCKED | COMPLETED. Use when creating a workload, answering pillar questions, generating an improvement plan, creating a milestone, or integrating with Trusted Advisor. Triggers: well-architected tool, well architected review, workload review, pillar, operational excellence, security, reliability, performance, cost optimization, sustainability, prosperity, improvement plan, milestone, trusted advisor.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwellarchitected-review-operator\u002FSKILL.md",[],[],{"skillNo":175,"name":176,"nameZh":6,"description":177,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":178,"categories":179,"keywords":180,"publishedAt":19},"01M7ADSH5JA9QHNPPHQCD7EVA7","wafv2-web-acl-deployer","Provisions AWS WAFv2 Web ACLs with correct production defaults: scope selection (CLOUDFRONT vs REGIONAL), managed rule groups (AWSManagedRulesCommonRuleSet, SQLiRuleSet, LinuxRuleSet, WindowsRuleSet, IPReputationList, BotControlRuleSet, AmazonIpReputationList, ATP), custom rules (byte match, IP set, regex pattern, geo match, size constraint, rate-based), rule priority ordering, logging destinations (Kinesis Firehose, CloudWatch Logs, S3), resource association (ALB, API Gateway, CloudFront), rate-based rules with aggregate keys (IP, forwarded IP), Challenge and CAPTCHA actions, and account takeover prevention. Emits a READY_TO_DEPLOY checklist. Use when creating a Web ACL, attaching managed rules, configuring rate limiting, enabling WAF logging, associating a Web ACL with an ALB\u002FAPI Gateway\u002FCloudFront, or configuring CAPTCHA\u002FChallenge actions. Triggers: create WAF Web ACL, WAFv2, managed rule groups, WAF rate limiting, WAF logging, WAF CAPTCHA, WAF Challenge action, bot control, ATP managed rules.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwafv2-web-acl-deployer\u002FSKILL.md",[],[],{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":187,"publishedAt":19},"01M7ADRYFAT8R73FBNCHRC573X","wafv2-web-acl-auditor","Audits AWS WAFv2 Web ACL configurations to determine whether the ACL provides effective protection: default-action posture (Allow vs Block), managed-rule-group coverage gaps, rule effectiveness (BLOCK vs COUNT, shadow\u002Fbypass rules, stale exclusions), rate-based rule correctness, logging and visibility configuration, and text-transformation bypass vectors. Emits a deterministic verdict per Web ACL. Use when reviewing a WAFv2 Web ACL for security posture, checking managed-rule coverage, validating rate-limit configuration, auditing WAF logging, or hardening a WAF before production deployment. Triggers: WAF, WAFv2, Web ACL, managed rule group, AWSManagedRules, rate-based rule, CAPTCHA, Challenge, OverrideAction, Count mode, forwarded IP, Bot Control, ATP, text transformation, WAF logging, WAF visibility, OWASP, SQLi, XSS, RFI.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwafv2-web-acl-auditor\u002FSKILL.md",[],[],{"skillNo":189,"name":190,"nameZh":6,"description":191,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":192,"categories":193,"keywords":194,"publishedAt":19},"01M7ADR8W7G72JX4KFGN03QK8Q","waf-rule-deployer","Provisions AWS WAFv2 rule sets with production defaults: Web ACL creation (CloudFront scope in us-east-1 vs Regional scope), rule groups (managed vs custom) with capacity planning in WCU (Web ACL Capacity Units, 1500 default per ACL), managed rule groups (AWSManagedRulesCommonRuleSet, AWSManagedRulesSQLiRuleSet, AWSManagedRulesAmazonIpReputationList, AWSManagedRulesLinuxRuleSet, AWSManagedRulesWindowsRuleSet, AWSManagedRulesUnixRuleSet), custom rules (byte-match, regex pattern set, geo-match, rate-based), IP set and regex pattern set resources, rule priority ordering (lowest number evaluated first), action types (allow, block, count, CAPTCHA, Challenge), bot control managed rule group, account takeover. Triggers: create WAF rule, WAF managed rule group, WAF custom rule, WAF byte match, WAF geo match, WAF rate based rule, WAF IP set, WAF regex pattern set, WAF WCU budget, WAF CloudFront ACL, WAF logging Kinesis Firehose, WAF bot control, WAF ATP, WAF label matching, WAF Challenge action, WAF CAPTCHA.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwaf-rule-deployer\u002FSKILL.md",[],[]]