🚨 Microsoft Teams Error: 'App package is invalid' — Cause, Fix, and Troubleshooting Guide

Overview

Uploading a custom app package through the Teams admin center or the “Upload a custom app” flow rejects the .zip before it ever installs. The upload dialog reports a generic packaging failure and points you at error details, but the underlying problem is almost always structural: file layout, icon dimensions, or a manifest that doesn’t validate.

App package is invalid. See the error details.

Symptoms

• The upload fails immediately in the admin center or client with no install taking place.
• The package validates locally with older tooling but is rejected by the current upload path.
• The app installs on one tenant but a re-zipped copy is rejected on another.
• Icons are missing or render as broken placeholders even when the upload succeeds elsewhere.
• CI produces a zip that a human can open normally but Teams still refuses.

Common Root Causes

• Files not at the zip root — manifest.json, the color icon, and the outline icon must sit at the archive root, not inside a wrapping folder. Zipping the containing directory (so the archive lists appPackage/manifest.json) is the single most common cause.
• Wrong icon dimensions — the color icon must be 192x192 PNG and the outline icon 32x32 PNG with a transparent background; other sizes or formats are rejected.
• Manifest schema errors — a field that violates the declared $schema/manifestVersion, a bad enum, or a missing required property.
• Invalid or mismatched id — the app id isn’t a valid GUID, or doesn’t match the registered app.
• Version problems — the version isn’t a valid three-part number, or you re-uploaded without bumping it for an update.
• Missing referenced files — icon filenames declared in the manifest don’t exist in the zip (or the case doesn’t match).

How to diagnose

Inspect the archive layout first — this catches the folder-nesting problem instantly.

# Files MUST be listed at the root, e.g. "manifest.json", NOT "appPackage/manifest.json"
unzip -l appPackage.zip

# Confirm the manifest is valid JSON and validate the schema
jq empty manifest.json && echo "JSON OK"
teamsapp validate --manifest-path ./manifest.json

Check the icon dimensions against the required sizes:

# ImageMagick: color must be 192x192, outline 32x32 with transparency
identify color.png outline.png

Cross-check the icon filenames referenced in the manifest against what’s actually in the zip:

jq '.icons' manifest.json

Fixes

Rebuild the zip so the three required files are at the archive root. Zip the files, not their parent directory:

cd appPackage
# Correct: adds manifest.json, color.png, outline.png at the root
zip -X ../app.zip manifest.json color.png outline.png

Avoid zip -r ../app.zip . from a parent directory, and never zip the folder itself, as both push the files under a subpath. Verify with unzip -l ../app.zip that the first column shows bare filenames.

Regenerate icons at the exact required dimensions if identify reports anything else:

# Resize/flatten to the required sizes
convert source-color.png -resize 192x192 color.png
convert source-outline.png -resize 32x32 -background none outline.png

Fix any schema issues the validator reports, ensure id is a valid GUID matching your registration, and bump version to a new three-part value before re-uploading updates. Re-run teamsapp validate until it passes, then upload the fresh zip.

What to watch out for

• The folder trap — dragging a folder into your OS “compress” action wraps everything under that folder name; always zip the contents.
• Case sensitivity — Color.png in the zip vs color.png in the manifest will fail on strict paths; keep casing identical.
• Icon background — the outline icon needs transparency; a white or colored background can be rejected or render poorly.
• Version reuse — re-uploading the same version for an update is treated as invalid; increment it.
• Extra junk in the zip — stray __MACOSX folders or hidden files add noise; keep the archive to the required files plus any legitimately referenced assets.
• GUID mismatch — an id that doesn’t match the registered app will pass local JSON checks but fail server-side validation.

Related

• Manifest Validation Failed
• Adaptive Card Unsupported Schema Version
• Bad Request / Invalid Request