General troubleshooting for Azure Bot Service bots
APPLIES TO: SDK v4
These frequently asked questions can help you to troubleshoot common bot development or operational issues.
How can I troubleshoot issues with my bot?
- Debug your bot's source code with Visual Studio Code or Visual Studio.
- Test your bot using the Emulator before you deploy it to the cloud.
- Deploy your bot to a cloud hosting platform such as Azure and then test connectivity to your bot by using the built-in web chat control on your bot's dashboard in the Azure portal. If you encounter issues with your bot after you deploy it to Azure, you might consider using this blog article: Understanding Azure troubleshooting and support.
- Rule out authentication as a possible issue.
- Test your bot on Web Chat, Teams, or any other channel you intend to use with your bot. This will help you to validate the end-to-end user experience.
- Consider testing your bot on channels that have additional authentication requirements such as Direct Line or Web Chat.
- Review the how-to debug a bot and the other debugging articles in that section.
How can I troubleshoot authentication issues?
For details about troubleshooting authentication issues with your bot, see troubleshooting Bot Framework authentication.
How do I test network connectivity between bots and a channel?
You can use the IP addresses, generated by the steps below, to verify if there is any rule blocking the connection with those addresses. See section Check firewall traces on failed connections.
Test connection from bot to channel
In your browser, navigate to the Azure portal.
Select your bot App Service whose connection you want to test.
In the left pane, in the Development Tools section, select Advanced Tools.
In the right pane, click Go. The Kudu information page is displayed.
In the top menu bar, click Debug console. Then, in the drop down menu, click CMD. The Kudu bot web app console is opened. For more information, see Kudu.

Run
nslookup directline.botframework.comand check if the DNS resolution is working. Notice thatnslookup(name server lookup) is a network administration command-line tool for querying the Domain Name System (DNS) to obtain domain name or IP address mapping, or other DNS records. If the DNS resolution is working, the response to this command will contain the relevant information.
The WHOIS IP Lookup Tool is useful to get information about IP addresses.
Run
curl -I directline.botframework.com. (The option-Iis used to obtain a response containing the header only.) Double check that an HTTP status of 301 is returned This is a check that there is connectivity.
Test connection from channel to bot
Because curl doesn't have access to the production site, and directline.botframework.com is on the public internet, you must use curl in simulation mode. Perform the steps shown below outside a Virtual Private Network (VNET), for example, using a cell phone hotspot. See also What is Azure Virtual Network?.
Run
nslookup ivr-sr-bot.botapps.amat.com. The DNS resolution is working if the response to this command contains relevant information.
Run
curl -I https://ivr-sr-bot.botapps.amat.com/api/messagesand check whether an appropriate HTTP status code is returned (for example, 405 method not allowed). The method specified in the request is not allowed for the resource identified by the specified URI. This is just a way to check that there is connectivity.
If you do not get the response from the bot, write down the client's IP address.
Check firewall traces on failed connections
Use the IP addresses from nslookup ivr-sr-bot.botapps.amat.com and nslookup directline.botframework.com and check if there is a rule blocking connection with those addresses on either direction.
I'm using the Bot Framework SDK for .NET. How can I troubleshoot issues with my bot?
Look for exceptions. In Visual Studio 2019, go to Debug > Windows > Exception Settings. In the Exceptions Settings window, select the Break When Thrown checkbox next to Common Language Runtime Exceptions. You may also see diagnostics output in your Output window when there are thrown or unhandled exceptions.
Look at the call stack. In Visual Studio, you can choose whether or you are debugging Just My Code or not. Examining the full call stack may provide additional insight into any issues.
Ensure all dialog methods end with a plan to handle the next message. All dialog steps need to feed into the next step of the waterfall, or end the current dialog to pop it off the stack. If a step is not correctly handled, the conversation will not continue like you expect. Take a look at the concept article for dialogs for more on dialogs.
What causes an error with HTTP status code 429 "Too Many Requests"?
An error response with HTTP status code 429 indicates that too many requests have been issued in a given amount of time. The body of the response should include an explanation of the problem and may also specify the minimum required interval between requests. One possible source for this error is the ngrok tool. If you are on a free plan and running into ngrok's limits, go to the pricing and limits page on their website for more options.
Why aren't my bot messages getting received by the user?
The message activity generated in response must be correctly addressed, otherwise it won't arrive at its intended destination. In the vast majority of cases you will not need to handle this explicitly; the SDK takes care of addressing the message activity for you.
Correctly addressing an activity means including the appropriate conversation IDs details along with details about the sender. In most cases, the message activity is sent in response to one that had arrived. Therefore, the addressing details can be taken from the inbound activity.
If you examine traces or audit logs, you can check to make sure your messages are correctly addressed. If they aren't, set a breakpoint in your bot and see where the IDs are being set for your message.
How can I run background tasks in ASP.NET?
In some cases, you may want to initiate an asynchronous task that waits for a few seconds and then executes some code to clear the user profile or reset conversation/dialog state. For details about how to achieve this, see How to run Background Tasks in ASP.NET. In particular, consider using HostingEnvironment.QueueBackgroundWorkItem.
My bot is slow to respond to the first message it receives. How can I make it faster?
Bots are web services and some hosting platforms, including Azure, automatically put the service to sleep if it does not receive traffic for a certain period of time. If this happens to your bot, it must restart from scratch the next time it receives a message, which makes its response much slower than if it was already running.
Some hosting platforms enable you to configure your service so that it will not be put to sleep. If your bot is hosted on Azure Bot Service Web Apps, navigate to your bot's service in the Azure portal, select Application settings, and then select Always on. This option is available in most, but not all, service plans.
How can I guarantee message delivery order?
The Bot Framework will preserve message ordering as much as possible. For example, if you send message A and wait for the completion of that HTTP operation before you initiate another HTTP operation to send message B. Some channels, such as SMS and email, do not guarentee ordering to the user's device.
Why are parts of my message text being dropped?
The Bot Framework and many channels interpret text as if it were formatted with Markdown. Check to see if your text contains characters that may be interpreted as Markdown syntax.
How can I support multiple bots at the same bot service endpoint?
This sample shows how to configure the Conversation.Container with the right MicrosoftAppCredentials and use a simple MultiCredentialProvider to authenticate multiple App IDs and passwords.
Identifiers
How do identifiers work in the Bot Framework?
For details about identifiers in the Bot Framework, see the Bot Framework guide to identifiers.
How can I get access to the user ID?
Bot Framework channels present the user's ID in the from.Id field of any Activity sent by the user. SMS and email messages will provide the raw user ID in this property. Some channels obscure the from.Id property so it contains unique ID for the user which differs from the user's ID in the channel. If you need to connect to an existing account, you can use a sign-in card and implement your own OAuth flow to connect the user ID to your own service's user ID.
Why are my Facebook user names not showing anymore?
Did you change your Facebook password? Doing so will invalidate the access token, and you will need to update your bot's configuration settings for the Facebook Messenger channel in the Azure portal.
Why is my Kik bot replying "I'm sorry, I can't talk right now"?
Bots in development on Kik are allowed 50 subscribers. After 50 unique users have interacted with your bot, any new user that attempts to chat with your bot will receive the message "I'm sorry, I can't talk right now." For more information, see Kik documentation.
How can I use authenticated services from my bot?
For Azure Active Directory authentication, see the Add authentication to your bot tutorial.
Note
If you add authentication and security functionality to your bot, you should ensure that the patterns you implement in your code comply with the security standards that are appropriate for your application.
How can I limit access to my bot to a pre-determined list of users?
Some channels, such as SMS and email, provide unscoped addresses. In these cases, messages from the user will contain the raw user ID in the from.Id property.
Other channels, such as Facebook and Slack, provide either scoped or tenanted addresses in a way that prevents a bot from being able to predict a user's ID ahead of time. In these cases, you will need to authenticate the user via a login link or shared secret in order to determine whether or not they are authorized to use the bot.
Why does my Direct Line 1.1 conversation start over after every message?
Note
This sections does not apply to the latest version of the Direct Line protocol, 3.0
If your Direct Line conversation appears to start over after every message, the from property is likely missing or null in messages that your Direct Line client sent to the bot. When a Direct Line client sends a message with the from property either missing or null, the Direct Line service automatically allocates an ID, so every message that the client sends will appear to originate from a new, different user.
To fix this, set the from property in each message that the Direct Line client sends to a stable value that uniquely represents the user who is sending the message. For example, if a user is already signed-in to a webpage or app, you might use that existing user ID as the value of the from property in messages that the user sends. Alternatively, you might choose to generate a random user ID on page-load or on application-load, store that ID in a cookie or device state, and use that ID as the value of the from property in messages that the user sends.
What causes the Direct Line 3.0 service to respond with HTTP status code 502 "Bad Gateway"?
Direct Line 3.0 returns HTTP status code 502 when it tries to contact your bot but the request does not complete successfully. This error indicates that either the bot returned an error or the request timed out. For more information about errors that your bot generates, go to the bot's dashboard within the Azure portal and click the "Issues" link for the affected channel. If you have Application Insights configured for your bot, you can also find detailed error information there.
Why do I get an Authorization_RequestDenied exception when creating a bot?
Permission to create Azure Bot Service bots are managed through the Azure Active Directory (AAD) portal. If permissions are not properly configured in the AAD portal, users will get the Authorization_RequestDenied exception when trying to create a bot service.
First check whether you are a "Guest" of the directory:
- Sign-in to Azure portal.
- Click All services and search for active.
- Select Azure Active Directory.
- Click Users.
- Find the user from the list and ensure that the User Type is not a Guest.

Once you verified that you are not a Guest, then to ensure that users within an active directory can create bot service, the directory administrator needs to configure the following settings:
- Sign-in to AAD portal. Go to Users and groups and select User settings.
- Under App registration section, set Users can register applications to Yes. This allows users in your directory to create bot service.
- Under the External users section, set Guest users permissions are limited to No. This allows guest users in your directory to create bot service.

Why can't I migrate my bot?
If your bot is registered in dev.botframework.com, and you want to migrate it to Azure, but are having issues migrating your bot, it might be because the bot belongs to a directory other than your default directory. Try these steps:
From the target directory, add a new user (via email address) that is not a member of the default directory, grant the user contributor role on the subscriptions that are the target of the migration.
From Dev Portal, add the user's email address as co-owners of the bot that should be migrated. Then sign out.
Sign in to Dev Portal as the new user and proceed to migrate the bot.
Where can I get more help?
- Leverage the information in previously answered questions on Stack Overflow, or post your own questions using the
botframeworktag. Please note that Stack Overflow has guidelines such as requiring a descriptive title, a complete and concise problem statement, and sufficient details to reproduce your issue. Feature requests or overly broad questions are off-topic; new users should visit the Stack Overflow Help Center for more details. - Consult BotBuilder issues in GitHub for information about known issues with the Bot Framework SDK, or to report a new issue.
- Leverage the information in the BotBuilder community discussion on Gitter.