Azure AI Foundry – Error saving knowledge base: property 'kind' does not exist on AgentKnowledgeSourceReference

Question

Hi everyone,

I am trying to create/save a Knowledge Base in Azure AI Foundry, but I am getting the following error:

Error saving knowledge base

The request is invalid. Details:
The property 'kind' does not exist on type
'Microsoft.WindowsAzure.Search.Core.Models.V2025_11_01_Preview.Agents.AgentKnowledgeSourceReference'
or is not present in the API version '2025-11-01-Preview'.

Make sure to only use property names that are defined by the type.

Environment:

• Azure AI Foundry
• Using Knowledge Base / Knowledge Source feature
• API version mentioned in error: 2025-11-01-Preview
• Data source: Excel / SharePoint / uploaded files
• Using Azure AI Search integration

What I have tried:

1. Recreating the knowledge source
2. Removing and re-adding the data source
3. Trying uploaded file instead of SharePoint
4. Refreshing the Foundry project

Questions:

1. Is this a known issue with the 2025-11-01-Preview API?
2. Is there a workaround or stable API version recommended?
3. Is this caused by schema mismatch between AI Foundry and Azure AI Search?
4. Should we avoid the Knowledge Base preview feature for now?

Any advice would be appreciated. Thanks! everyone

Answer 1

Hi everyone,

If you are encountering the following validation error when creating a Knowledge Base for your Agent in Microsoft AI Foundry:

“Error saving knowledge base. The request is invalid. Details: The property 'kind' does not exist on type 'Microsoft.WindowsAzure.Search.Core.Models.V2025_11_01_Preview.Agents.AgentKnowledgeSourceReference' or is not present in the API version '2025-11-01-Preview'.”

This is caused by a platform schema mismatch bug in the portal's internal frontend wrapper (ai.azure.com/nextgen/api/). The UI drops required properties during serialization, and the 2025-11-01-Preview API endpoint fails to process the nested agent schema properties correctly in certain regions (like swedencentral).

You can completely bypass this bug by creating the resources directly using the Azure AI Search Data-Plane API (Stable version 2026-04-01) via the Azure CLI and curl.

Here is the exact step-by-step solution to provision your Knowledge Base and attach it to your Agent:

Step 1: Get an Azure AI Search Scoped Token

Open your terminal, log into your Azure CLI account, and pull an access token scoped explicitly for Azure AI Search:

Bash

# Log in and set your active subscription

Step 2: Create the Knowledge Source Directly

Run the following curl command to provision your Knowledge Source mapping. Note that we target the stable 2026-04-01 API and explicitly inject the required "kind": "azureBlob" and "kind": "azureOpenAI" fields that the UI is currently breaking:

Bash

curl -X PUT 

Note: If Azure returns a naming conflict error indicating a component already exists, simply change <YOUR-KS-NAME> slightly (e.g., append -v2) to route around cached metadata states.

Step 3: Create the Knowledge Base Wrapper

Once the Knowledge Source returns a success confirmation, link it to the orchestration layer. CRITICAL: Ensure you explicitly declare the "modelName" parameter using an accepted naming convention format (e.g., gpt-4o, gpt-4.1), otherwise the backend engine will reject the model configuration setup.

Bash

curl -X PUT 

Step 4: Link it in the Azure AI Foundry UI

Go back to your Azure AI Foundry Studio browser window.

Hard refresh the page to update the portal UI engine cache.

Open your Agent configuration panel and go to the Knowledge tab.

Select Add Existing Knowledge Base instead of attempting a fresh creation.

Choose <YOUR-KB-NAME> from the list and hit save.

Your agent will instantly bind onto the manually built operational data-plane connection map cleanly, completely avoiding the preview registration bug!

Answer 2

I have the same issue; it seems to be a bug. I solved it by adding the knowledge source manually through the API.

Answer 3

Successful creation of knowledge base when "kind" property is removed from the request API.

Answer 4

I think the 2025‑11‑01 preview has no kind on that ref‑type, and setting the KB to 2026‑04‑01 is the step that matches the schema for that API version.

Answer 5

The error message indicates a schema mismatch in the preview API version being used by Azure AI Foundry for knowledge bases. In the 2025-11-01-preview API, the AgentKnowledgeSourceReference type does not define a kind property, so any request payload that includes kind on that type is rejected.

From the available documentation:

• Knowledge bases and knowledge sources are separate objects. A knowledge base references one or more knowledge sources.
• For knowledge bases created via the 2025-11-01-preview REST/Python surface, the knowledge_sources collection is required, but the schema for the knowledge source reference does not include a kind property.
• The kind property is defined on the knowledge source object itself (for example, kind = "searchIndex" for a search index knowledge source), not on the reference used inside the knowledge base.

This means the error is caused by the preview implementation sending a kind field where the backend type does not expect it. That is a backend/preview bug rather than a configuration issue with the data source (Excel/SharePoint/uploaded files) or Azure AI Search.

Based on the context:

1. Is this a known issue with the 2025-11-01-Preview API?
   The error arises specifically from the 2025-11-01-preview schema for AgentKnowledgeSourceReference, which does not support kind. This is consistent with a preview API mismatch and should be treated as a preview limitation/bug.
2. Is there a workaround or stable API version recommended?
   The generally available agentic retrieval features use the 2026-04-01 REST API version. For programmatic work, using the GA 2026-04-01 version for knowledge bases and knowledge sources is the stable path. The Azure portal and Microsoft Foundry portal continue to expose preview-only capabilities, but the GA API is recommended for production workloads.
3. Is this caused by schema mismatch between AI Foundry and Azure AI Search?
   Yes. The error explicitly states that the property kind does not exist on AgentKnowledgeSourceReference for API version 2025-11-01-preview. That indicates the Foundry front end (or its SDK) is sending a field that the Azure AI Search backend type for that preview version does not define.
4. Should the Knowledge Base preview feature be avoided for now?
   For production or stable scenarios, the preview feature should be avoided and the GA 2026-04-01 agentic retrieval APIs should be used instead. Preview features are provided without an SLA and are not recommended for production workloads. If the scenario requires the Foundry portal’s preview-only capabilities, expect issues like this and track fixes via the product channel; otherwise, prefer the GA API.

A practical path forward is:

1. Define knowledge sources (for example, search index knowledge sources) using the GA schema, where kind is on the knowledge source object itself.
2. Create a knowledge base using the GA 2026-04-01 API, referencing those knowledge sources.
3. Use the retrieve action to validate the knowledge base and its connection to Azure AI Search.

---

References:

• Create a knowledge base in Azure AI Search (rest)
• Create a knowledge base in Azure AI Search (python)
• Create a search index knowledge source (rest)
• Create a search index knowledge source (python)