Troubleshooting

Start with the user-visible signal, then follow the delivery path. You should rarely need raw Azure logs.

Check these first

Installation or sign-in

The Setup page is blank

1. Open https://tdckbprod-flex-prod.azurewebsites.net/api/health.
2. If it fails, the backend or network is unavailable; this is not an SSO problem.
3. If it succeeds, reload Teams and try the web client to separate desktop cache from service availability.

“This app hasn't been set up for your organization”

A tenant admin has not completed the one-time consent flow. Follow Admin consent, then sign out and back in.

Sign-in loops or access denied

Open Diagnostics from the admin navigation and run checks. A valid token is not enough: the tenant must be installed and the user must hold Connector.Admin.

A card never arrived

1. Click Test. This bypasses filters and tests the actual destination.
2. Read Last delivery. Red means the request reached us and delivery failed; “no events yet” means no accepted event reached that subscription.
3. Check the sender. Open GitHub Recent Deliveries, GitLab webhook history, or the equivalent platform log.
4. Check intentional suppression. Status filters, pipeline allowlists, quiet hours, failure-after-success, dedupe, and incident mode can all suppress a new card.

Destination-specific failures

Bot channel: 403 or “not part of conversation”

The app was removed or is not installed in that channel. Add it to the channel, reselect the channel, and Test again.

Incoming webhook fails

The Teams Workflows URL was deleted, expired, or belongs to another workflow. Recreate the workflow and paste the new URL into the subscription. The URL is write-only and will not be displayed later.

DM delivery fails

The recipient must have opened or messaged the app so the bot has a valid 1:1 conversation reference. Ask them to open the app, then reselect them.

Incident card stopped updating

If somebody deleted the card, the next event should create a replacement. If it does not, inspect Last delivery for a Bot Framework error and verify the bot remains in the channel.

API update failures

PUT returns 428

GET the subscription and send its exact response ETag as If-Match. Wildcard * is rejected.

PUT returns 412

Another user changed the subscription. GET the latest state, reconcile your desired configuration, and retry. Do not blindly replay the stale body: PUT clears omitted optional fields.

Platform change returns 400

Platform is part of the ingest URL and cannot change in place. Create a new subscription and update the sender.

Monitoring says degraded

1. Call /api/ready. A 503 indicates a service dependency problem.
2. Call authenticated /api/monitoring/status and identify failing subscriptions.
3. Correlate their timestamps with deployments, sender retries, and Microsoft service health.
4. For self-hosted systems, inspect Application Insights requests, dependencies, and exceptions.

Before contacting support

Include the approximate UTC time, platform, subscription name, HTTP status, and a screenshot of Last delivery or Diagnostics. Never send ingest URLs, API keys, webhook URLs, tokens, raw authorization headers, or full payloads containing secrets.