{
  "slug": "asc-png-alpha-channel-rejected",
  "url": "https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected",
  "markdown_url": "https://insidetheloop.dev/fixes/asc-png-alpha-channel-rejected.md",
  "title": "ASC CLI: \"image has an alpha channel or transparency\" on screenshot upload",
  "description": "asc 5.13.0+ rejects any PNG with an alpha channel, even fully opaque, before upload. Flatten it to RGB with ImageMagick or export JPEG.",
  "tool": {
    "id": "asc",
    "name": "ASC CLI",
    "long_name": "App Store Connect CLI (asc)",
    "url": "https://insidetheloop.dev/tools/asc",
    "latest_version": "5.13.0"
  },
  "error": "image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha",
  "variants": [
    "Error: asset-library images upload: --file: image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha"
  ],
  "output": "Error: screenshots upload: \"./opaque-rgba.png\": image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha",
  "exit_code": 1,
  "command": "asc screenshots upload --version-localization LOC_123 --path ./opaque-rgba.png --device-type IPHONE_DUO",
  "versions": {
    "affected": "5.13.0 and later",
    "first_bad": "5.13.0",
    "last_good": "5.12.1",
    "fixed_in": null,
    "tested": [
      "5.12.1",
      "5.13.0"
    ]
  },
  "cause": "Since ASC CLI 5.13.0 (released 2026-10-07), `asc screenshots upload` and `asc asset-library images upload` refuse any PNG whose colour type carries an alpha channel (RGBA or grey+alpha) or a transparency chunk, even when every pixel is fully opaque.",
  "fix": {
    "summary": "Flatten the image onto a background and drop the alpha channel (RGB PNG), or export it as JPEG, then upload again.",
    "commands": [
      "# ImageMagick 7 (brew install imagemagick, apt-get install imagemagick)",
      "magick screenshot.png -background white -alpha remove -alpha off PNG24:screenshot-rgb.png",
      "asc screenshots upload --version-localization <LOC_ID> --path ./screenshot-rgb.png --device-type IPHONE_DUO",
      "",
      "# or JPEG, which has no alpha channel",
      "magick screenshot.png -background white -alpha remove -alpha off -quality 92 screenshot.jpg"
    ],
    "note": "In ImageMagick's documentation, `-alpha remove` composites the image over the background colour (set with `-background`) and `-alpha off` disables the alpha channel. With the `PNG24:` prefix, our output was 8-bit RGB (PNG colour type 2). The check runs before authentication, so it fails the same way in CI with or without App Store Connect credentials. `asc asset-library images upload` prints the same message after `--file:` and exits 2 instead of 1."
  },
  "reproduction": {
    "ran_at": "2026-10-07T14:12:12Z",
    "environment": "A fresh Debian 13 VM from `bin/sandbox-run` (Node.js 24, root, online, no credentials for any service), destroyed after the run. Test images were generated with Node's zlib: a 1398x2034 RGBA PNG with every alpha byte 255, one with the top half fully transparent, and a plain RGB PNG.",
    "steps": [
      {
        "label": "Before: the same opaque RGBA file passes the local checks and stops at authentication",
        "version": "5.12.1",
        "command": "asc screenshots upload --version-localization LOC_123 --path ./opaque-rgba.png --device-type IPHONE_DUO",
        "output": "Error: screenshots upload: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init')\nHint: Run `asc auth status` to see configured credentials. To add an API key, create one at https://appstoreconnect.apple.com/access/integrations/api and run `asc auth login --name MyKey --key-id KEY_ID --issuer-id ISSUER_ID --private-key /path/to/AuthKey_KEY_ID.p8` (or set ASC_KEY_ID/ASC_ISSUER_ID/ASC_PRIVATE_KEY_PATH).",
        "exit": 3
      },
      {
        "label": "After: rejected locally",
        "version": "5.13.0",
        "command": "asc screenshots upload --version-localization LOC_123 --path ./opaque-rgba.png --device-type IPHONE_DUO",
        "output": "Error: screenshots upload: \"./opaque-rgba.png\": image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha",
        "exit": 1
      },
      {
        "label": "Asset Library upload of the same file",
        "version": "5.13.0",
        "command": "asc asset-library images upload --library-id LIB_123 --file ./opaque-rgba.png",
        "output": "Error: asset-library images upload: --file: image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha\n[… trimmed 23 lines …]",
        "exit": 2
      },
      {
        "label": "Fix: flatten with ImageMagick 7.1.1-43 (no output)",
        "version": "5.13.0",
        "command": "magick opaque-rgba.png -background white -alpha remove -alpha off PNG24:fixed-opaque-rgba.png",
        "output": "",
        "exit": 0
      },
      {
        "label": "The flattened files are 8-bit RGB (PNG colour type 2) with no transparency chunk, read with a 9-line PNG header script",
        "version": "5.13.0",
        "command": "node pnginfo.mjs fixed-opaque-rgba.png fixed-half-transparent.png",
        "output": "fixed-opaque-rgba.png: 1398x2034 bit_depth=8 colour_type=2 tRNS=false\nfixed-half-transparent.png: 1398x2034 bit_depth=8 colour_type=2 tRNS=false",
        "exit": null
      },
      {
        "label": "Fix verified: the flattened file passes the alpha check and reaches authentication",
        "version": "5.13.0",
        "command": "asc screenshots upload --version-localization LOC_123 --path ./fixed-opaque-rgba.png --device-type IPHONE_DUO",
        "output": "Error: screenshots upload: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init')\nHint: Run `asc auth status` to see configured credentials. To add an API key, create one at https://appstoreconnect.apple.com/access/integrations/api and run `asc auth login --name MyKey --key-id KEY_ID --issuer-id ISSUER_ID --private-key /path/to/AuthKey_KEY_ID.p8` (or set ASC_KEY_ID/ASC_ISSUER_ID/ASC_PRIVATE_KEY_PATH).",
        "exit": 3
      }
    ]
  },
  "why": {
    "text": "Pull request #2938 (merged 2026-10-06, shipped in 5.13.0) rejects \"RGBA/grayscale-alpha PNGs and transparency chunks before reservation\", so a bad image fails before asc reserves an asset in App Store Connect instead of after; ordinary RGB PNGs and JPEGs are still accepted.",
    "url": "https://github.com/rorkai/App-Store-Connect-CLI/pull/2938",
    "source": "rorkai/App-Store-Connect-CLI PR #2938"
  },
  "tool_page": "https://insidetheloop.dev/tools/asc#gotcha-opaque-rgba-png-rejected-as-having-an-alpha-channel",
  "related": [
    {
      "slug": "asc-flag-must-be-passed-after-subcommand",
      "error": "Error: --stars must be passed after the subcommand name (asc reviews list [flags])",
      "url": "https://insidetheloop.dev/fixes/asc-flag-must-be-passed-after-subcommand"
    }
  ],
  "sources": [
    {
      "title": "Reject App Store image alpha before reserving uploads (PR #2938)",
      "url": "https://github.com/rorkai/App-Store-Connect-CLI/pull/2938",
      "read": "2026-10-07"
    },
    {
      "title": "ASC CLI 5.13.0 release notes",
      "url": "https://github.com/rorkai/App-Store-Connect-CLI/releases/tag/5.13.0",
      "read": "2026-10-07"
    },
    {
      "title": "ImageMagick command-line options: -alpha",
      "url": "https://imagemagick.org/script/command-line-options.php#alpha",
      "read": "2026-10-07"
    }
  ],
  "date_published": "2026-10-07T14:15:32Z",
  "date_modified": "2026-10-07T14:15:32Z",
  "verified": {
    "date": "2026-10-07",
    "versions": [
      "5.12.1",
      "5.13.0"
    ]
  }
}