Troubleshooting

Container Does Not Start

Run docker logs privman-teams-bot to check the error. Common causes:

  • Missing required environment variable — KeyError appears in config.py.

  • PRIVMAN_BASE_URL does not end with /Tms — causes an authentication failure on the first poll.

  • Port 8080 is already in use on the host — Docker returns Ports are not available.

Poller Shows "0 Pending — No Changes" Continuously

The container is healthy but Privilege Manager has no pending approvals. Trigger a real elevation request from a managed endpoint to confirm the bot responds.

Test in Web Chat Returns an Error

If the Azure Portal Web Chat returns "There was an error sending this message to your bot":

  • The bot endpoint is wrong, missing /api/messages, or pointing to a stopped ngrok tunnel.

  • The App ID, password, or tenant does not match between the Bot resource and the container's environment variables.

  • The container is not running — check docker ps.

Bot Replies in Web Chat but Not in Teams

  • The Teams channel is not enabled on the Bot resource — run az bot msteams create.

  • The app manifest botId does not match MicrosoftAppId.

  • Custom app sideloading is blocked by tenant policy — contact your Teams admin.

  • The bot was sideloaded but not added to the specific channel where you are testing.

Bot Receives Mentions but Does Not Post Approval Cards

  • No Saved conversation reference line appears in the logs — send a message to the bot to register the conversation.

  • The conversations volume is not mounted — references are lost on restart. Check: docker inspect privman-teams-bot | findstr Mounts

ERR_NGROK_3200 — Endpoint Offline

The ngrok agent stopped. Re-run ngrok http 8080 in a persistent terminal. If the URL changed, update the bot endpoint:

az bot update -g <rg> -n <bot-name> --endpoint "https://<new-url>/api/messages"

401 Unauthorized on POST /api/messages

  • MicrosoftAppPassword is wrong or has been rotated in Azure AD.

  • MicrosoftAppTenantId does not match the tenant the App Registration lives in.

  • MicrosoftAppType is SingleTenant in the environment but the App Registration is MultiTenant, or vice versa.

Auto-Approve Commands Fail with "Authentication Failed"

  • KEY_VAULT_URL is not set or is not reachable from the container.

  • The container's service principal or managed identity does not have the Key Vault Secrets Officer role.

  • The AZURE_CLIENT_* values are incorrect when running locally.

Quick Reference

Item Value
Docker image delineaxpm/privman-teams:latest
Default poll interval 60 seconds
Auto-approve duration 4 hours
Bot listen port 8080
Required endpoint suffix /api/messages
Conversations volume privman-conversations
Data path inside container /app/data
Runtime user Non-root
Health check curl http://localhost:8080/health