MetricSign
EN|NLRequest Access
Medium severityconfiguration

Power BI Refresh Error:
DF-Xml-UnsupportedExternalReferenceResource

What does this error mean?

The XML file or schema references an external resource (external DTD, entity file, or HTTP URL) that ADF does not support. ADF can only resolve schema references pointing to Azure storage.

Common causes

  • 1The XML file contains a DOCTYPE declaration that references an external DTD via an HTTP URL (e.g., <!DOCTYPE note SYSTEM 'http://example.com/note.dtd'>)
  • 2The XSD schema file configured in the dataset uses xs:import or xs:include with a URL-based location attribute pointing to an external HTTP endpoint
  • 3The XML file references external XML entity files via ENTITY declarations with SYSTEM URLs pointing to non-Azure locations
  • 4The DTD or XSD is hosted on a public CDN or W3C schema repository URL that ADF cannot reach from the data flow runtime

How to fix it

  1. 1Open the XML file and check for DOCTYPE declarations or external entity references — look for SYSTEM 'http://.' or PUBLIC identifiers.
  2. 2If the XML has a DOCTYPE with an external DTD URL: remove the DOCTYPE declaration if DTD validation is not needed, or host the DTD file in Azure Blob Storage and update the dataset schema path accordingly.
  3. 3Open the XSD schema file and check xs:import and xs:include elements — replace any schemaLocation URLs that point to HTTP endpoints with relative paths, and place all referenced XSD files in the same Azure storage container.
  4. 4If DTD validation is not required, disable DTD processing in the XML dataset settings — set Validation mode to None.
  5. 5If the XML files are generated by a third-party system that always includes the external reference, consider pre-processing the files with a Copy Activity to strip the DOCTYPE declaration before the data flow reads them.

Frequently asked questions

Why can't ADF resolve external HTTP URLs in XML schema references?

ADF Mapping Data Flows run on isolated Spark clusters where outbound HTTP to arbitrary URLs is blocked. All schema and reference files must be in Azure storage accessible to the ADF instance.

How do I remove a DOCTYPE declaration from XML files without editing each file manually?

Use a pre-processing step to strip the DOCTYPE line — a Copy Activity, Azure Function, or script. Alternatively, configure the XML parser to ignore DTD processing if the data itself is valid.

Is this the same error as DF-Xml-InvalidReferenceResource?

Related but distinct. InvalidReferenceResource means the path is invalid or inaccessible within supported storage types. UnsupportedExternalReferenceResource means the reference points to a type (HTTP URL, file system path) that ADF does not support.

Will downstream Power BI datasets be affected?

Yes — the pipeline fails and the downstream table receives no new data.

Official documentation: https://learn.microsoft.com/en-us/azure/data-factory/data-flow-troubleshoot-guide

Other configuration errors