What causes DynamicsAlternateKeyNotFound?

The alternate key name specified in the copy activity sink settings is misspelled or uses the wrong key name. The alternate key was deleted or deactivated in Dataverse after the ADF pipeline was created. The alternate key was created on a different Dataverse environment and was never deployed to this environment

How do I fix DynamicsAlternateKeyNotFound?

Log into Dataverse and go to Settings > Customizations > Entities > [Entity] > Keys to verify the alternate key exists and is active.. Correct the alternate key name in the ADF copy activity sink settings to match the key's schema name in Dataverse.. If the alternate key was removed, recreate it or switch the upsert strategy to use the primary GUID key.

Medium severitydata source

Power BI Refresh Error:
DynamicsAlternateKeyNotFound

What does this error mean?

The alternate key configured for the ADF Dynamics upsert does not exist in the Dataverse entity definition or has been deactivated.

Common causes

1The alternate key name specified in the copy activity sink settings is misspelled or uses the wrong key name
2The alternate key was deleted or deactivated in Dataverse after the ADF pipeline was created
3The alternate key was created on a different Dataverse environment and was never deployed to this environment

How to fix it

1Log into Dataverse and go to Settings > Customizations > Entities > [Entity] > Keys to verify the alternate key exists and is active.
2Correct the alternate key name in the ADF copy activity sink settings to match the key's schema name in Dataverse.
3If the alternate key was removed, recreate it or switch the upsert strategy to use the primary GUID key.

Frequently asked questions

Does this error affect all pipeline runs or just the current one?

Depends on the root cause. A persistent misconfiguration fails every run; a transient issue may resolve on retry. Check the run history.

Can this error appear in Azure Data Factory and Microsoft Fabric pipelines?

Yes — the same connector errors appear in both ADF and Fabric Data Factory pipelines.

How do I see the full error detail for an ADF pipeline failure?

In ADF Monitor, click the failed run, then the failed activity. The detail pane shows the error code, message, and sub-error codes.

Will downstream Power BI datasets be affected when an ADF pipeline fails?

Yes — a dataset refreshing after the pipeline will use stale data or fail if the target table was cleared. The Power BI refresh may succeed while serving wrong data.

Official documentation: https://learn.microsoft.com/en-us/azure/data-factory/connector-troubleshoot-dynamics-dataverse