agents-store 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.16for modern features.idmust equalTEAMS_APP_ID.bots[].botIdmust equalBOT_IDin.env.webApplicationInfo.resourcemust equalapi://<host>/<AAD client id>for SSO.validDomainsmust 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-updateto pull the latest CLI.- Search
https://github.com/microsoft/teams-sdk/issuesfor the exact error string.