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

  • Dynamics 365 Client Diagnostics

    15 March’ 2018

    Main cause of Performance Issues: Bandwidth and latency are the primary characteristics which affects the performance o...

    Read more
  • Closing Blind Shift in MPOS and CPOS in Dynamics 365 for Retail

    15 March’ 2018

    Manual For closing Blind shift in POS: Blind shifts terminate the currently ongoing shift and when logged in a new shif...

    Read more
  • Persistent Filters in the Power BI Service

    13 March’ 2018

    Introduction: The feature is finally release, and it is power BI has announced general availability of persistent filt...

    Read more
  • Cause and Solution for Scribe MSMQ not receiving Message from AX

    10 March’ 2018

    Issue: Microsoft Message Queuing (MSMQ) service running on Server might be unable to receive messages. Therefore, messa...

    Read more
  • User Privileges on SharePoint – D365 Document Integration

    10 March’ 2018

    Overview: Often, we wonder what could be wrong where we see a generic error on Documents in Dynamics 365. Something lik...

    Read more