| name | troubleshoot |
| description | Use this skill when the user is debugging a Microsoft Teams app problem — sideload failures, "bot did not reply", SSO `signin.token-exchange` errors, manifest validation, endpoint mismatches, Adaptive Card rendering issues, or any "why isn't my Teams bot working" question. Triggers on "Teams bot not responding", "sideload error", "Teams 401", "Teams 403", "Teams app manifest invalid". |
Troubleshooting Teams apps
A focused triage guide. Walk through the sections in order — most problems land in the first three.
For integrating Teams into an existing server (often the underlying cause of "no reply"), see references/integrate-existing-server.md.
1. Bot does not reply
| Symptom | Likely cause | Fix |
|---|
| Message is sent in Teams, server logs show nothing | Endpoint wrong | teams app update <id> --endpoint "https://<host>/api/messages" |
Server logs show activity, send throws | Bot credentials wrong | Confirm BOT_ID / BOT_PASSWORD against teams app get <id> --json |
| DevTools shows inbound but no outbound | Handler returned before send | Add log.info lines to trace handler flow |
| Outbound shown in DevTools, nothing in Teams | Tunnel is down (devtunnel/ngrok) | Restart tunnel; re-run teams app update --endpoint with the new URL |
Always start with DevTools (http://localhost:3979/devtools). If the activity is not visible there, the request never reached your server — the problem is between Teams and your host.
2. Sideload errors
| Symptom | Likely cause | Fix |
|---|
| "Manifest validation failed" | Schema mismatch | Bump manifestVersion to match the features used (1.16+ for execute actions, etc.) |
| "App already installed" | Older sideload still active | Uninstall the app in Teams → reinstall |
| "Invalid icon" | Icon missing / wrong size | Ensure color.png (192×192) and outline.png (32×32) under appPackage/ |
| "Tenant policy disallows sideloading" | Admin policy | Use a Developer Program tenant, or ask the admin to allow custom app uploads |
3. SSO failures
| Symptom | Likely cause | Fix |
|---|
signin.token-exchange never fires | OAuth connection name mismatch | Match connectionName in OAuthCard to the Bot Service config |
| Exchange returns "invalid resource" | webApplicationInfo.resource wrong | Set to api://<host>/<AAD client id> and re-deploy manifest |
| Graph call returns 401 | User token bound to wrong audience | Inspect the JWT at jwt.ms — aud must match the AAD app's API URI |
| Graph call returns 403 | Missing delegated permission | Add the scope in AAD → grant admin consent |
Full SSO setup: references/integrate-existing-server.md covers the integration angle; the dedicated authentication/references/sso-setup.md has the Azure-side checklist.
4. Adaptive Card issues
| Symptom | Likely cause | Fix |
|---|
| Card renders as plain text | Attachment shape wrong | Use cardAttachment('adaptive', card); do not hand-build the envelope |
Action.Submit does nothing | Bot has no card.action.<id> handler | Add app.on('card.action.<id>', …); verify ids match |
| Input value missing in submission | Input has no id | Every *Input needs an id (first constructor arg) |
| Card looks fine in Designer but blank in Teams | Old client version | Confirm Teams desktop/web is up to date; some elements require client 1.5+ |
5. AI / streaming
| Symptom | Likely cause | Fix |
|---|
| Streaming flashes nothing in a channel | Streaming only works in 1:1 | Gate on conversation.conversationType === 'personal'; send the full text otherwise |
| OpenAI returns 401 | Wrong key | Confirm OPENAI_API_KEY or AZURE_OPENAI_API_KEY in .env |
| Tool fires twice | Same tool registered in prompt.function and mcp.tool | Pick one host per tool |
| 15s timeout on long calls | Teams drops the request | Send a typing indicator + reply later via app.send(conversationId, …) |
6. Manifest sanity checks
jq '.manifestVersion, .id, .bots[]?.botId, .webApplicationInfo?, .validDomains' appPackage/manifest.json
manifestVersion ≥ 1.16 for modern features.id must equal TEAMS_APP_ID.bots[].botId must equal BOT_ID in .env.webApplicationInfo.resource must equal api://<host>/<AAD client id> for SSO.validDomains must include every host referenced by tabs or dialogs.
7. Network / proxy
curl -fsS "https://<host>/api/messages" -X POST -H "Content-Type: application/json" -d '{}'
A bare POST should return a non-200 (Teams normally signs requests). If it returns ECONNREFUSED or timeout, the tunnel or host itself is unreachable from your machine — fix that before debugging higher layers.
8. When all else fails
- Restart the dev server (
npm run dev).
- Reinstall the app in Teams (uninstall + sideload again).
teams self-update to pull the latest CLI.- Search
https://github.com/microsoft/teams-sdk/issues for the exact error string.
