🚨 Microsoft Teams Error Guide: Adaptive Card 'unsupported schema version' — Target a Version Teams Renders

Overview

An Adaptive Card that declares a version newer than the Teams host can render fails to display its rich content. Teams may show a stripped-down card, fall back to the fallbackText, or render nothing where the card should be. The card designer and browser console report the schema mismatch:

Adaptive Card error: unsupported schema version "1.6".
Host supports up to version 1.5. Elements introduced after 1.5 were dropped.

Symptoms

• A card renders perfectly in the online Adaptive Card Designer but appears blank or as plain fallbackText in the Teams client.
• Newer elements (Table, Input.Text with regex, certain RichTextBlock features) silently disappear.
• Desktop Teams renders the card but mobile or older clients do not (or vice versa).
• The bot’s message posts successfully (HTTP 201) yet users see an empty attachment.
• Console/log shows the card was parsed but elements were skipped due to version.

Common Root Causes

• Version ahead of the host — the card sets "version": "1.6" (or higher) while Teams supports up to 1.5 for most surfaces.
• No fallback declared — newer elements/actions lack a fallback, so an unsupported element drops the whole container.
• Copy-pasted sample — a snippet from newer docs or another host (Outlook, Windows) uses features Teams hasn’t shipped.
• Mixed surfaces — the same card is sent to bots, message extensions, and connectors that support different maximum versions.
• Client skew — users on old Teams builds render older schema than the current maximum.

Diagnostic Workflow

Inspect the card’s declared version — this is the first thing to check:

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.6",          <-- Teams may not support this
  "body": [ ... ]
}

Post the attachment and confirm Teams accepts it but drops content. A bot send looks like:

curl -X POST "${SERVICE_URL}/v3/conversations/${CONV_ID}/activities" \
  -H "Authorization: Bearer ${BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "attachments": [{
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": { "type":"AdaptiveCard", "version":"1.5",
        "body":[{"type":"TextBlock","text":"Deploy complete"}] }
    }]
  }'

Add fallback to any element that might be too new so it degrades gracefully:

{
  "type": "Table",
  "fallback": {
    "type": "TextBlock",
    "text": "Results: see the dashboard link below.",
    "wrap": true
  }
}

Validate against the target version with the Adaptive Cards CLI or Designer set to the Teams host so unsupported elements are flagged before you ship.

Example Root Cause Analysis

A platform team built a deploy-summary card using an Table element and set "version": "1.6" because that’s what the sample they copied used. In the Designer (defaulting to the latest schema) it looked great. In production, desktop Teams showed only the header and mobile showed nothing. The bot logged HTTP 201 on every send, so it looked like a rendering bug on Microsoft’s side.

The real cause: Teams rendered up to 1.5, so the 1.6-declared card had its newer Table dropped, and because no fallback was set, the surrounding container collapsed. Lowering version to 1.5, replacing the Table with a ColumnSet/FactSet, and adding fallback blocks to any borderline element made the card render identically across desktop, web, and mobile.

Prevention Best Practices

• Target the version Teams actually supports (1.5 is a safe baseline across current surfaces) rather than the newest schema.
• Add a fallback to every element or action introduced after your target version.
• Always set a meaningful fallbackText at the card root so a total failure still communicates something.
• Test in the real Teams client (desktop, web, mobile), not only the Adaptive Card Designer.
• Keep one card version policy per surface; don’t reuse a bot card verbatim for connectors/Outlook.
• Validate cards in CI against the target schema version before deploy.

Quick Command Reference

# Validate a card against a schema version (Adaptive Cards CLI)
npx adaptivecards-cli validate --version 1.5 ./card.json

# Grep your cards for versions ahead of the Teams baseline
grep -R '"version"' ./cards/ | grep -vE '1\.[0-5]"'

# Lint that every non-baseline element has a fallback
grep -L '"fallback"' ./cards/*.json

Conclusion

“Unsupported schema version” is a targeting mistake: your card declares features the Teams host cannot render. Because Teams often returns success on the post and merely drops elements, the failure looks silent. Pin the card version to what Teams supports, add fallback blocks for anything newer, set root fallbackText, and validate in CI plus the real client. Do that and your cards render consistently instead of collapsing to blank attachments.