Indexed SharePoint Knowledge Source returns HTTP 500 with multiple includeFolder filters

Question

Indexed SharePoint Knowledge Source returns HTTP 500 with multiple includeFolder filters

Fredrik Skau 0

We are experiencing a reproducible HTTP 500 error when creating an Indexed SharePoint Knowledge Source in Azure AI Search using multiple includeFolder filters.

Environment

Service: Azure AI Search

Region: France Central

SKU: Basic

API version: 2026-08-01-preview

Knowledge source type: indexedSharePoint

Data source container: useQuery

Authentication: Microsoft Entra application using federated managed identity

Problem

We need to index selected folders within a SharePoint document library.

According to Microsoft's documentation for the classic SharePoint indexer, multiple includeFolder parameters can be specified using semicolon separation.

Our configuration follows this format:

includeFolder=https://tenant.sharepoint.com/site/library/project/folder1;includeFolder=https://tenant.sharepoint.com/site/library/project/folder2

Both folders belong to the same SharePoint site and document library.

However, creating the Indexed SharePoint Knowledge Source fails with HTTP 500 whenever the query contains two or more includeFolder parameters.

Reproduction results

We tested nine SharePoint folders individually.

Each individual folder successfully created a knowledge source (HTTP 201).

Combining two or more individually valid folder paths consistently resulted in HTTP 500.

The failure occurs during knowledge source creation, before document indexing begins.

Invalid folder paths return HTTP 400, indicating a different failure condition.

The combined query with nine folders is approximately 1,500 characters.

The error response is:

Target Knowledge Source with name 'test-sharepoint-source' failed to create or update

After the failed request, an orphaned indexer may remain without its corresponding data source. The knowledge source itself is not created.

Expected behavior

We expect multiple includeFolder parameters to work as documented for the underlying SharePoint indexer, or for the API to return a clear validation error if this configuration is unsupported.

Questions

Does the indexedSharePoint knowledge source type officially support multiple includeFolder parameters in API version 2026-08-01-preview?

Is this a known issue with the managed knowledge source provisioning process?

Is there a supported workaround that allows multiple folder filters while retaining the managed Indexed SharePoint pipeline?

If multiple filters are currently unsupported, is this functionality planned?

Why this matters

We need to index selected folder categories across a large SharePoint project archive.

Creating one knowledge source and search index per project or category is not practical due to Azure AI Search resource limits.

We would prefer to retain the managed Indexed SharePoint Knowledge Source architecture rather than build and maintain a separate indexing pipeline.

Any clarification from the Azure AI Search engineering team would be greatly appreciated.

Documentation

SharePoint indexer: https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sharepoint-online

Indexed SharePoint Knowledge Source: https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-sharepoint-indexedWe are experiencing a reproducible HTTP 500 error when creating an Indexed SharePoint Knowledge Source in Azure AI Search using multiple includeFolder filters.

Environment

Service: Azure AI Search

Region: France Central

SKU: Basic

API version: 2026-08-01-preview

Knowledge source type: indexedSharePoint

Data source container: useQuery

Authentication: Microsoft Entra application using federated managed identity

Problem

We need to index selected folders within a SharePoint document library.

According to Microsoft's documentation for the classic SharePoint indexer, multiple includeFolder parameters can be specified using semicolon separation.

Our configuration follows this format:

includeFolder=https://tenant.sharepoint.com/site/library/project/folder1;includeFolder=https://tenant.sharepoint.com/site/library/project/folder2

Both folders belong to the same SharePoint site and document library.

However, creating the Indexed SharePoint Knowledge Source fails with HTTP 500 whenever the query contains two or more includeFolder parameters.

Reproduction results

We tested nine SharePoint folders individually.

Each individual folder successfully created a knowledge source (HTTP 201).

Combining two or more individually valid folder paths consistently resulted in HTTP 500.

The failure occurs during knowledge source creation, before document indexing begins.

Invalid folder paths return HTTP 400, indicating a different failure condition.

The combined query with nine folders is approximately 1,500 characters.

The error response is:

Target Knowledge Source with name 'test-sharepoint-source' failed to create or update

After the failed request, an orphaned indexer may remain without its corresponding data source. The knowledge source itself is not created.

Expected behavior

We expect multiple includeFolder parameters to work as documented for the underlying SharePoint indexer, or for the API to return a clear validation error if this configuration is unsupported.

Questions

Does the indexedSharePoint knowledge source type officially support multiple includeFolder parameters in API version 2026-08-01-preview?

Is this a known issue with the managed knowledge source provisioning process?

Is there a supported workaround that allows multiple folder filters while retaining the managed Indexed SharePoint pipeline?

If multiple filters are currently unsupported, is this functionality planned?

Why this matters

We need to index selected folder categories across a large SharePoint project archive.

Creating one knowledge source and search index per project or category is not practical due to Azure AI Search resource limits.

We would prefer to retain the managed Indexed SharePoint Knowledge Source architecture rather than build and maintain a separate indexing pipeline.

Any clarification from the Azure AI Search engineering team would be greatly appreciated.

Documentation

SharePoint indexer:
https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sharepoint-online

Indexed SharePoint Knowledge Source:
https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-sharepoint-indexed

0 comments

1 answer

Your answer

Answer 1

Hello @Fredrik Skau

The documented syntax supports multiple includeFolder clauses. The folders are separated by semicolons, and the includeFolder parameter is repeated:

"container": {
  "name": "useQuery",
  "query": "includeFolder=https://contoso.sharepoint.com/sites/project/Shared Documents/FolderA;includeFolder=https://contoso.sharepoint.com/sites/project/Shared Documents/FolderB"
}

Each value must be a complete SharePoint folder URL, and all included folders must belong to the same document library. Root-only paths are unsupported.

Because one includeFolder works while adding a second reproducibly returns HTTP 500, first verify that:

Both URLs reference folders in the same document library.
Neither value is the document-library root.
The query repeats includeFolder= for each folder.
Entries are separated with a semicolon.
The application has at least read access to both locations. If Sites.Selected is used, the application must receive an explicit permission grant on every applicable SharePoint site; Entra admin consent alone does not provide site access.

If those requirements are satisfied, the request format is documented as supported. I cannot find an official Microsoft limitation stating that an indexed SharePoint knowledge source accepts only one includeFolder. The HTTP 500 response therefore appears inconsistent with the documented behavior, but only Microsoft can confirm whether this is a defect in the preview knowledge-source creation path.

The indexed SharePoint knowledge source is itself a preview feature. It automatically creates a SharePoint data source, skillset, index, and indexer, and it inherits the SharePoint indexer’s prerequisites and limitations. Preview functionality is not covered by a service-level agreement and can change before general availability.

Possible supported workarounds are:

Create one indexed SharePoint knowledge source for each folder and reference both from the same knowledge base. Azure AI Search knowledge bases can contain one or more knowledge sources.
If the required selection can be represented that way, use includeLibrary with one or more excludeFolder clauses. Both filters are documented for the SharePoint indexer.
Create the SharePoint data source and indexer directly, then expose the resulting index through a Search Index knowledge source. Microsoft supports using an existing compliant index as an agentic knowledge source.

For escalation, include the complete sanitized request body, API version, response body, HTTP response headers and request ID, UTC timestamp, search-service resource ID, and results showing that each folder works independently but fails when combined.

References:

Help make this community better for everyone: If this answer helped or resolved your issue, please accept it or upvote it. If not, share more details in a comment so we can continue the discussion and find the right solution. Thank you.