Fix pages / ASC CLI

ASC CLI: "image has an alpha channel or transparency" on screenshot upload

Error: screenshots upload: "./opaque-rgba.png": image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha

Tool: App Store Connect CLI (asc). Versions: Affected: 5.13.0 and later; last version without this error: 5.12.1; we reproduced it on 5.12.1, 5.13.0. Exit code 1.

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: Flatten the image onto a background and drop the alpha channel (RGB PNG), or export it as JPEG, then upload again.

# 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

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.

The same cause also prints:

Error: asset-library images upload: --file: image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha

Last verified 2026-10-07 (5.12.1, 5.13.0). Page updated . Also as Markdown and JSON.

How did we reproduce the ASC CLI error?

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. Run on . Failing command: asc screenshots upload --version-localization LOC_123 --path ./opaque-rgba.png --device-type IPHONE_DUO.

Before: the same opaque RGBA file passes the local checks and stops at authentication (ASC CLI 5.12.1):

$ asc screenshots upload --version-localization LOC_123 --path ./opaque-rgba.png --device-type IPHONE_DUO
Error: screenshots upload: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init')
Hint: 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

After: rejected locally (ASC CLI 5.13.0):

$ asc screenshots upload --version-localization LOC_123 --path ./opaque-rgba.png --device-type IPHONE_DUO
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

Asset Library upload of the same file (ASC CLI 5.13.0):

$ asc asset-library images upload --library-id LIB_123 --file ./opaque-rgba.png
Error: asset-library images upload: --file: image has an alpha channel or transparency; re-export it as RGB PNG or JPEG without alpha
[… trimmed 23 lines …]
# exit 2

Fix: flatten with ImageMagick 7.1.1-43 (no output) (ASC CLI 5.13.0):

$ magick opaque-rgba.png -background white -alpha remove -alpha off PNG24:fixed-opaque-rgba.png
# exit 0

The flattened files are 8-bit RGB (PNG colour type 2) with no transparency chunk, read with a 9-line PNG header script (ASC CLI 5.13.0):

$ node pnginfo.mjs fixed-opaque-rgba.png fixed-half-transparent.png
fixed-opaque-rgba.png: 1398x2034 bit_depth=8 colour_type=2 tRNS=false
fixed-half-transparent.png: 1398x2034 bit_depth=8 colour_type=2 tRNS=false

Fix verified: the flattened file passes the alpha check and reaches authentication (ASC CLI 5.13.0):

$ asc screenshots upload --version-localization LOC_123 --path ./fixed-opaque-rgba.png --device-type IPHONE_DUO
Error: screenshots upload: missing authentication. Run 'asc auth login' or create /root/.asc/config.json (see 'asc auth init')
Hint: 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 does ASC CLI print this error?

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. (rorkai/App-Store-Connect-CLI PR #2938)

Related ASC CLI fixes and pages

Sources

Last verified: 2026-10-07.