General troubleshooting for Azure AI 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?

1. Debug your bot's source code with Visual Studio Code or Visual Studio.
2. Test your bot using the Bot Framework Emulator before you deploy it to the cloud.
3. 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.
4. Rule out authentication as a possible issue.
5. 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.
6. Consider testing your bot on channels that have extra authentication requirements such as Direct Line or Web Chat.
7. 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's any rule blocking the connection with those addresses. See section Check firewall traces on failed connections.

Test connection from bot to channel

1. In your browser, go to the Azure portal.

2. Select your bot App Service whose connection you want to test.

3. In the left pane, in the Development Tools section, select Advanced Tools.

4. In the right pane, select Go. The Kudu information page is displayed.

5. In the top menu bar, select Debug console. Then, in the drop-down menu, select CMD. The Kudu bot web app console is opened. For more information, see Kudu.

   

6. Run nslookup directline.botframework.com and check if the DNS resolution is working. Notice that nslookup (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.

7. Run curl -I directline.botframework.com. (The option -I is used to obtain a response containing the header only.) Double check that an HTTP status of 301 is returned to verify there's 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?.

1. Run nslookup ivr-sr-bot.botapps.amat.com. The DNS resolution is working if the response to this command contains relevant information.

   

2. Run curl -I https://ivr-sr-bot.botapps.amat.com/api/messages and check whether an appropriate HTTP status code is returned (for example, 405 method not allowed). The method specified in the request isn't allowed for the resource identified by the specified URI. This is just a way to check that there's connectivity.

   

3. If you don't 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's 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're debugging Just My Code or not. Examining the full call stack can provide more 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 isn't correctly handled, the conversation won't 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're 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 most cases, you won't need to handle this explicitly; the SDK takes care of addressing the message activity for you.

To correctly address an activity, include the appropriate conversation ID 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 doesn't 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 won't be put to sleep. If your bot is hosted on Azure AI Bot Service Web Apps, go 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, don't guarantee to order in which the user will receive messages.

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.

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'll need to update your bot's configuration settings for the Facebook Messenger channel in the Azure portal.

How can I use authenticated services from my bot?

For Microsoft Entra ID 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'll need to authenticate the user via a login link or shared secret in order to determine whether or not they're authorized to use the bot.

Why does my Direct Line 1.1 conversation start over after every message?

Note

This section doesn't 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 doesn't 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 select the "Issues" link for the affected channel. If you configured Application Insights 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 AI Bot Service bots are managed through the Microsoft Entra ID portal. If permissions aren't properly configured in the Microsoft Entra ID admin center, users will get the Authorization_RequestDenied exception when trying to create a bot service.

First check whether you're a "Guest" of the directory:

1. Sign-in to Azure portal.
2. Select All services and search for active.
3. Select Microsoft Entra ID.
4. Select Users.
5. Find the user from the list and ensure that the User Type isn't a Guest.

Once you verified that you're 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:

1. Sign-in to Microsoft Entra ID admin center. Go to Users and groups and select User settings.
2. Under App registration section, set Users can register applications to Yes. This allows users in your directory to create bot service.
3. 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:

1. From the target directory, add a new user (via email address) that isn't a member of the default directory, grant the user contributor role on the subscriptions that are the target of the migration.

2. From Dev Portal, add the user's email address as co-owners of the bot that should be migrated. Then sign out.

3. Sign in to Dev Portal as the new user and proceed to migrate the bot.

Where can I get more help?

• Search for previously answered questions on Stack Overflow, or post your own questions using the botframework tag. 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.
• The BotBuilder community discussion on Gitter.