🚨 Microsoft Teams Error Guide: 'Manifest parsing has failed' App Package Upload — Fix the manifest.json

Overview

Uploading or publishing a Teams app package fails when the manifest.json doesn’t conform to the declared schema. The Teams admin center, Developer Portal, or teamsapp CLI reports the validation error and refuses the package.

Manifest parsing has failed.
"manifestVersion" is required. | "id" must be a valid GUID. |
"icons.color" file "color.png" was not found in the package. |
"validDomains" must not contain a wildcard at the top level.

Symptoms

• Sideloading a .zip app package returns “Something went wrong” / “manifest parsing has failed”.
• The Developer Portal flags specific fields red on import.
• The package uploads to one tenant but is rejected by the store validation.
• Icons appear broken or the app installs but tabs/bots don’t wire up.
• CI packaging succeeds but the produced zip fails validation.

Common Root Causes

• Wrong or missing manifestVersion — the $schema and manifestVersion don’t point at a version Teams accepts.
• Invalid id — the app id isn’t a valid GUID, or doesn’t match the registered app ID.
• Package/manifest mismatch — icon filenames in the manifest don’t exist in the zip, or the manifest isn’t at the zip root.
• Bad URLs/domains — contentUrl/configurationUrl not HTTPS, or validDomains contains a wildcard or a domain not covering your URLs.
• ID mismatches — bots[].botId, webApplicationInfo.id, or composeExtensions[].botId don’t match the real registrations.

Diagnostic Workflow

Validate the manifest JSON and its schema before packaging:

# Is it even valid JSON?
jq empty manifest.json && echo OK

# Validate against the declared schema with the Teams CLI
teamsapp validate --manifest-path ./appPackage/manifest.json

Check the declared version and required IDs:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.17",
  "id": "11112222-3333-4444-5555-666677778888",
  "developer": { "name": "...", "websiteUrl": "https://example.com",
                 "privacyUrl": "https://example.com/privacy",
                 "termsOfUseUrl": "https://example.com/terms" },
  "icons": { "color": "color.png", "outline": "outline.png" },
  "validDomains": ["tab.example.com"]
}

Confirm the package structure matches — manifest and both icons at the zip root:

unzip -l appPackage.zip
# Archive:  appPackage.zip
#   manifest.json
#   color.png      (192x192)
#   outline.png    (32x32, transparent)

Verify referenced IDs exist:

# botId in the manifest must match a real Azure Bot registration
az bot show --name "$BOT_NAME" -g "$RG" --query properties.msaAppId

Example Root Cause Analysis

A team automated app packaging in CI. The build templated manifest.json from environment variables, and a misnamed variable left manifestVersion empty in production packages. Sideloading returned “manifest parsing has failed” with no obvious cause because the CI logs showed a successful zip.

Running teamsapp validate locally against the produced package immediately flagged the missing manifestVersion and, separately, that validDomains had picked up a wildcard (*.example.com) that top-level validation rejects. Fixing the template variable, pinning manifestVersion/$schema to a supported version, and replacing the wildcard with the explicit tab domain made the package validate. They then added teamsapp validate as a required CI gate so a malformed manifest could never ship again.

Prevention Best Practices

• Pin $schema and manifestVersion to a version Teams currently supports and keep them in sync.
• Ensure the app id is a valid GUID matching your Developer Portal registration.
• Keep manifest.json, color.png (192x192), and outline.png (32x32 transparent) at the zip root with names matching the manifest.
• Use HTTPS everywhere and list every host your URLs use in validDomains (no top-level wildcards).
• Match botId, webApplicationInfo.id, and compose-extension IDs to real registrations.
• Run teamsapp validate (or the Developer Portal validator) as a required CI step before packaging.

Quick Command Reference

# Validate JSON + schema
jq empty manifest.json && teamsapp validate --manifest-path manifest.json

# Inspect package layout (manifest + icons at root)
unzip -l appPackage.zip

# Check icon dimensions
identify color.png outline.png   # ImageMagick

# Confirm bot/app IDs referenced actually exist
az bot show -n "$BOT_NAME" -g "$RG" --query properties.msaAppId

Conclusion

“Manifest parsing has failed” is a schema-conformance problem: a missing version, an invalid GUID, a URL/domain violation, or a package whose files don’t match the manifest. Validate the manifest against its declared schema, confirm the zip contains the right files at the root, and make every referenced ID and domain real. Wiring teamsapp validate into CI turns manifest errors into a fast, pre-upload failure instead of a mysterious rejection in the admin center.