Troubleshooting for QnA Maker

The curated list of the most frequently asked questions regarding the QnA Maker service will help you adopt the service faster and with better results.


The QnA Maker service is being retired on the 31st of March, 2025. A newer version of the question and answering capability is now available as part of Azure AI Language. For question answering capabilities within the Language Service, see question answering. Starting 1st October, 2022 you won’t be able to create new QnA Maker resources. For information on migrating existing QnA Maker knowledge bases to question answering, consult the migration guide.

Manage predictions

How can I improve the throughput performance for query predictions?

Answer: Throughput performance issues indicate you need to scale up for both your App service and your Cognitive Search. Consider adding a replica to your Cognitive Search to improve performance.

Learn more about pricing tiers.

How to get the QnAMaker service endpoint

Answer: QnAMaker service endpoint is useful for debugging purposes when you contact QnAMaker Support or UserVoice. The endpoint is a URL in this form:

  1. Go to your QnAMaker service (resource group) in the Azure portal

    QnAMaker Azure resource group in Azure portal

  2. Select the App Service associated with the QnA Maker resource. Typically, the names are the same.

    Select QnAMaker App Service

  3. The endpoint URL is available in the Overview section

    QnAMaker endpoint

Manage the knowledge base

I accidentally deleted a part of my QnA Maker, what should I do?

Answer: Do not delete any of the Azure services created along with the QnA Maker resource such as Search or Web App. These are necessary for QnA Maker to work, if you delete one, QnA Maker will stop working correctly.

All deletes are permanent, including question and answer pairs, files, URLs, custom questions and answers, knowledge bases, or Azure resources. Make sure you export your knowledge base from the Settings page before deleting any part of your knowledge base.

Why is my URL(s)/file(s) not extracting question-answer pairs?

Answer: It's possible that QnA Maker can't auto-extract some question-and-answer (QnA) content from valid FAQ URLs. In such cases, you can paste the QnA content in a .txt file and see if the tool can ingest it. Alternately, you can editorially add content to your knowledge base through the QnA Maker portal.

How large a knowledge base can I create?

Answer: The size of the knowledge base depends on the SKU of Azure search you choose when creating the QnA Maker service. Read here for more details.

Why can't I see anything in the drop-down when I try to create a new knowledge base?

Answer: You haven't created any QnA Maker services in Azure yet. Read here to learn how to do that.

How do I share a knowledge base with others?

Answer: Sharing works at the level of a QnA Maker service, that is, all knowledge bases in the service will be shared. Read here how to collaborate on a knowledge base.

Can you share a knowledge base with a contributor that is not in the same AAD tenant, to modify a knowledge base?

Answer: Sharing is based on Azure role-based access control. If you can share any resource in Azure with another user, you can also share QnA Maker.

If you have an App Service Plan with 5 QnAMaker knowledge bases. Can you assign read/write rights to 5 different users so each of them can access only 1 QnAMaker knowledge base?

Answer: You can share an entire QnAMaker service, not individual knowledge bases.

How can I change the default message when no good match is found?

Answer: The default message is part of the settings in your App service.

  • Go to your App service resource in the Azure portal

qnamaker appservice

  • Select the Settings option

qnamaker appservice settings

  • Change the value of the DefaultAnswer setting
  • Restart your App service

qnamaker appservice restart

Why is my SharePoint link not getting extracted?

Answer: See Data source locations for more information.

The updates that I made to my knowledge base are not reflected on publish. Why not?

Answer: Every edit operation, whether in a table update, test, or setting, needs to be saved before it can be published. Be sure to select Save and train button after every edit operation.

Does the knowledge base support rich data or multimedia?


Multimedia auto-extraction for files and URLs

  • URLS - limited HTML-to-Markdown conversion capability.
  • Files - not supported

Answer text in markdown

Once QnA pairs are in the knowledge base, you can edit an answer's markdown text to include links to media available from public URLs.

Does QnA Maker support non-English languages?

Answer: See more details about supported languages.

If you have content from multiple languages, be sure to create a separate service for each language.

Manage service

When should I restart my app service?

Answer: Refresh your app service when the caution icon is next to the version value for the knowledge base in the Endpoint keys table on the User Settings page.

I deleted my existing Search service. How can I fix this?

Answer: If you delete an Azure AI Search index, the operation is final and the index cannot be recovered.

I deleted my `testkb` index in my Search service. How can I fix this?

Answer: In case you deleted the testkb index in your Search service, you can restore the data from the last published KB. Please use the recovery tool RestoreTestKBIndex available on GitHub.

I am receiving the following error: Please check if QnA Maker App service's CORS settings allow or if there are any organization specific network restrictions. How can I resolve this?

Answer: In the API section of the App service pane, update the CORS setting to * or "". If this doesn't resolve the issue, check for any organization-specific restrictions.

When should I refresh my endpoint keys?

Answer: Refresh your endpoint keys if you suspect that they have been compromised.

Can I use the same Azure AI Search resource for knowledge bases using multiple languages?

Answer: To use multiple language and multiple knowledge bases, the user has to create a QnA Maker resource for each language. This will create a separate Azure search service per language. Mixing different language knowledge bases in a single Azure search service will result in degraded relevance of results.

How can I change the name of the Azure AI Search resource used by QnA Maker?

Answer: The name of the Azure AI Search resource is the QnA Maker resource name with some random letters appended at the end. This makes it hard to distinguish between multiple Search resources for QnA Maker. Create a separate search service (naming it the way you would like to) and connect it to your QnA Service. The steps are similar to the steps you need to do to upgrade an Azure search.

When QnA Maker returns `Runtime core is not initialized,` how do I fix it?

Answer: The disk space for your app service might be full. Steps to fix your disk space:

  1. In the Azure portal, select your QnA Maker's App service, then stop the service.

  2. While still on the App service, select Development Tools, then Advanced Tools, then Go. This opens a new browser window.

  3. Select Debug console, then CMD to open a command-line tool.

  4. Navigate to the site/wwwroot/Data/QnAMaker/ directory.

  5. Remove all the folders whose name begins with rd.

    Do not delete the following:

    • KbIdToRankerMappings.txt file
    • EndpointSettings.json file
    • EndpointKeys folder
  6. Start the App service.

  7. Access your knowledge base to verify it works now.

Why is my Application Insights not working?

Answer: Please cross check and update below steps to fix the issue:

  1. In App Service -> Settings group -> Configuration section -> Application Settings -> Name "UserAppInsightsKey" parameters is configured properly and set to the respective application insights Overview tab ("Instrumentation Key") Guid.

  2. In App Service -> Settings group -> "Application Insights" section -> Make sure app insights is enabled and connected to respective application insights resource.

My Application Insights is enabled but why is it not working properly?

Answer: Please follow the below given steps:

  1. Copy the value of '“APPINSIGHTS_INSTRUMENTATIONKEY” name' into 'UserAppInsightsKey' name by overriding if there is some value already present there.

  2. If the 'UserAppInsightsKey' key does not exist in app settings, please add a new key with that name and copy the value.

  3. Save it and this will automatically restart the app service. This should resolve the issue.

Integrate with other services including Bots

Do I need to use Bot Framework in order to use QnA Maker?

Answer: No, you do not need to use the Bot Framework with QnA Maker. However, QnA Maker is offered as one of several templates in Azure AI Bot Service. Bot Service enables rapid intelligent bot development through Microsoft Bot Framework, and it runs in a server-less environment.

How can I create a new bot with QnA Maker?

Answer: Follow the instructions in this documentation to create your Bot with Azure AI Bot Service.

How do I use a different knowledge base with an existing Azure AI Bot Service?

Answer: You need to have the following information about your knowledge base:

  • Knowledge base ID.
  • Knowledge base's published endpoint custom subdomain name, known as host, found on Settings page after you publish.
  • Knowledge base's published endpoint key - found on Settings page after you publish.

With this information, go to your bot's app service in the Azure portal. Under Settings -> Configuration -> Application settings, change those values.

The knowledge base's endpoint key is labeled QnAAuthkey in the ABS service.

Can two or more client applications share a knowledge base?

Answer: Yes, the knowledge base can be queried from any number of clients. If the response from the knowledge base appears to be slow, or timed out, consider upgrading the service tier for the app service associated with the knowledge base.

How do I embed the QnA Maker service in my website?

Answer: Follow these steps to embed the QnA Maker service as a web-chat control in your website:

  1. Create your FAQ bot by following the instructions here.
  2. Enable the web chat by following the steps here

Data storage

What data is stored and where is it stored?


When you create your QnA Maker service, you selected an Azure region. Your knowledge bases and log files are stored in this region.