Testing and debugging Cortana Skills

The following are the options available to test and debug your skill.

  • Use Bot Framework's emulator to test and debug your skill while you're developing it. The emulator lets you interact with your bot and see the messages that are exchanged. For details about using the emulator, see Debug with the emulator. Currently, the emulator does not support passing user profile and contextual information to the skill.

  • Use the debugger in Visual Studio Code to walk through your code as it executes in the console window. For details, see Debug a Bot Service bot.

  • Use the Chat window in the Bot Framework portal. Typically, you do this after you configure your Cortana channel and deploy the service to confirm that it's running.

  • Enable debug in Cortana so you can see the message exchange between Cortana and your skill. For information about enabling debugging, see Enable debugging in Cortana.

For details about debugging your skill in Azure's continuous publishing environment, see Debug an Azure Bot Service bot.

But before you start debugging your skill, check out Troubleshooting tips and Known Issues.


If you found an error in someone else's Cortana skill, use the feedback button in Cortana to report it.

Enable debugging in Cortana

If Cortana reports an error when running your skill, follow these steps to turn on Cortana's debugging. When enabled, Cortana displays all errors and message exchanges on her canvas.

  1. Log in to the old skills dashboard using the Microsoft account (MSA) that you used to configure your Cortana channel.
  2. Click Debug in the left pane.
  3. Check Debug mode for Cortana to enable debugging.
  4. Start Cortana on the system that you want to test your skill on.
  5. Make sure you're signed in using the same MSA you used to sign into the dashboard with. For details, see Get started.
  6. Click the Home icon on Cortana's menu bar to ensure that your computer is refreshed with the updated skills information from the dashboard.
  7. Click Cortana's microphone icon and invoke your skill. For information about invoking skills, see Invocation name guidelines.
  8. The canvas includes a debug button that you click to see the message exchange details.

Debugging Information

Troubleshooting tips

The following provides suggestions for solving common problems.

Issue Tip
I can't invoke my skill Check the following:
  • If you just saved your skill, press the Home icon on Cortana's menu bar. This updates Cortana's list of known skills on the computer with changes from Cortana's dashboard.
  • Make sure that you enabled debugging (see Enable debugging in Cortana).
  • Make sure that you signed into Cortana using the same MSA that you used to sign in to Cortana's dashboard.
  • Ensure that you are properly invoking your skill.
  • Verify that Cortana uses the correct name when she invokes your skill (she types the name in the Type here to search box as you speak).
  • Ensure that your device is set to one of the locales listed in Supported Cortana locales.
  • Ensure that your microphone is configured. For details, see Get started.
Cortana isn't spelling my invocation name correctly when I say it Check the following:
  • If you just saved your skill for the first time, it can take up to 10 minutes for the Cortana to recognize it as a skill invocation name.
  • If you just saved your skill, try pressing the Home icon in Cortana's menu bar to refresh her list of known skills.
  • Your invocation name may not be well designed, which makes it difficult for Cortana to recognize it. Take a look at the Invocation Guidelines for tips on creating a well-designed invocation name.
I can't create more than 20 skills You may associate a maximum of 20 skills to a Microsoft accounts (MSA). If you create more than 20 skills, simply use an additional MSA.
I get a DownstreamDependencyFailed error You get this error when the service endpoint you created, failed to respond. For example:
  • If your service takes too long to respond, Cortana will time-out the request.
  • If the response message is not formatted correctly based on the Bot Framework schema.
  • If your service returns a status code other than 200.
I can invoke my skill, but no one else can Ensure that you deployed your skill. If you want to make your skill available to a group of people, such as your family and friends, use the Publish to Group option. If you want everyone to have access to your skill, use the Publish to World option.

NOTE: If your skill includes code that checks the skill ID in the request, the ID is different between the deployed to self, group, and world versions of your skill (your skill has a unique ID for each deployment).
I've logged into the Cortana dashboard but don't see my skills Ensure that you signed in to the dashboard with the same MSA that you used to configure the Cortana channel with in the Bot Framework portal.
SSML reads XML characters aloud If Cortana reads out the XML characters of your, the XML is likely invalid. Be sure that all opening tags have closing tags and vice-versa. Consider using an XML library to ensure that your XML is properly formatted.
Cortana returns Forbidden error Cortana tried to connect to your service but received a 403 Forbidden error. Ensure that your service endpoint is configured to accept POST requests, not GET requests.

Additional resources

Stack Overflow forums

Azure debugging resources

Azure Web Apps

Azure Functions

Bot Framework troubleshooting guides