21 Dec’15

Dynamics CRMKnown issue when using Web API with Alternate key feature


With the release of Web API, Dynamics CRM now allows developers to build robust solutions and integrations using modern REST APIs consumed through OData.

While working on a CRM customization by leveraging the Web API, we found an issue that causes the API to stop working when we use the Alternate Key with the same name as the schema name of a field. This only applies to custom entities. In the section below we have defined the issue and a workaround.


Recently we were working on a requirement using the CRM web API but we were not able to access the web API using the entity endpoint.

When calling the endpoint from the browser, instead of displaying the metadata result in the browser, it generates an error. It simply says that the ‘Object reference not set to an instance of an object’ (we love this error!). This typically happens when during coding we forget to initialize the object. So getting this particular error when calling our endpoint, we were confused.

Microsoft has now confirmed that this is a known issue and they will resolve it soon. But for now, the only fix is to delete the key and publish the customization. So we removed the alternate key and generated a new one. This got the endpoint working again!

We were not able to understand how an alternate key will stop the web API from working. They ask use to delete the alternate key from the system which we had created recently. As soon as we deleted the key and published the customization we found that the WEB API working.

Example: The below screen shots confirm the issue.

Step 1: Browse to the Web API endpoint. You can see that it works.



Step 2: Define Alternate Key – to replicate the issue we created a field and an alternate key with the same name-



Step 3: Browse to the same endpoint – Now when trying to browse to the same endpoint we get the below error-



So there is a known issue when using Web API and Alternate Key for custom entities. Currently there is no resolution to this issue but to delete the alternate key and have a unique name which does not match with name field ‘s schema name.
Hope you found this useful!

Written by

Team Member


3 thoughts on “Known issue when using Web API with Alternate key feature”

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload the CAPTCHA.

Want to streamline your business processes?

  • This field is for validation purposes and should be left unchanged.

Recent Articles

  • Reading more then 10K records in D3FOE OData API

    11 July’ 2018

    Introduction: We all know Dynamics 365 Finance and Operations has limitation of 10K records to be fetched at a time usi...

    Read more
  • Paging in D365 Customer Engagement v9.0

    10 July’ 2018

    Introduction: The Xrm.retrieveMultipleRecords method is used to retrieve a collection of records in Dynamics 365 Custom...

    Read more
  • Set up Dynamics 365 connection in Microsoft Social Engagement

    10 July’ 2018

    Introduction: This blog explains how to Set up Dynamics 365 connection in Microsoft Social Engagement. Steps to be follo...

    Read more
  • Voice of the Customer failed to install

    10 July’ 2018

    Introduction: Many people face issues in installing Voice of Customer solution on v9 environment and trying repeatedly ...

    Read more
  • Scribe Insight AX as a Web Service Find Block issue

    10 July’ 2018

    Introduction: If we need to look up for any value from AX then we do it by using a Find Block in Scribe Insight Eg: Basi...

    Read more