Azure Data Factory Pipeline Errors: A Reference Index of Common Failures

Azure Data Factory does not raise a single class of error. A failed pipeline run can produce a numeric code in the 2xxx, 3xxx, or 5xxx range, a UserError* class name from the copy activity, an HRESULT from the self-hosted integration runtime, or a bare .NET exception name like OutOfMemoryException. The shape of the error tells you where it came from before you read the message.

Three log surfaces produce these errors and they do not always agree:

• Run log — the per-pipeline run history in the ADF Studio Monitoring tab. Shows the activity that failed, the duration, and the error message returned by that activity. This is the surface you reach by clicking the failed run.
• Activity log — the per-activity diagnostic detail behind each pipeline activity. For a copy activity, this is where you see UserErrorAzureBlobOperationFailed or UserErrorCopyActivityInvalidSinkConfiguration. For a self-hosted IR activity, this is where the HRESULT and stack trace land.
• Trigger log — the trigger run history. A pipeline that never started because the schedule trigger failed will show up here, not in the run log. Easy to miss if you only check the pipeline view.

Reading the wrong log is the first place engineers lose time. A pipeline shown as "queued" in the run log can have a trigger-level failure that is only visible in the trigger log. A copy activity that returns a generic "failed" status in the run log usually has the actual UserError* class buried two clicks deep in the activity-level details.

An ADF failure rarely stays in ADF. Most production pipelines exist to land data into a layer that something else reads — a lakehouse Power BI Direct Lake reads from, a Fabric warehouse a dbt project transforms, a Snowflake table a downstream BI dataset depends on.

Three cascade patterns cover the majority of incidents data teams handle:

The silent zero-row load. A copy activity completes without an error but writes zero rows because a source filter changed, a partition is empty, or a UserErrorInvalidColumnReferenced was caught and swallowed by an OnError activity. Power BI refreshes successfully on the empty table. The dashboard shows yesterday's cached data because Direct Lake fell back. Nobody is paged.

The late-but-completed pipeline. The ADF pipeline runs 22 minutes longer than its baseline because the self-hosted integration runtime hit UserErrorSelfHostedIntegrationRuntimeBusyWithFullTask and queued the run. The pipeline succeeds, but it finishes after the 06:00 Power BI refresh has already started. The refresh reads the previous day's snapshot and the Monday board report shows last week's numbers.

The downstream credential break. The pipeline fails with UserErrorOAuthTokenExpiredOrRevoked against a linked service. The dbt project that runs downstream sees no new partition and skips the model with a freshness check, which is correct behaviour but produces no alert. Six hours later, somebody notices.

In all three the ADF error itself is recoverable in minutes — once you find it. The damage is the time between the failure and the moment a human sees the alert.

For an end-to-end view of how ADF, Databricks, dbt, and Power BI fit together, see end-to-end data lineage from ADF to Power BI.

ADF errors group into a handful of failure modes. Use this index to identify which class of problem you are looking at, then click through to the dedicated fix page for the specific code.

#### Configuration (most common)

These errors fire when the pipeline definition, linked service, or self-hosted integration runtime configuration is wrong. Tenant mismatches, missing assemblies, JVM not installed, ACLs not granted. Common after IR upgrades or tenant migrations.

#### Data source

The pipeline reached the source or sink, but something about the data, the schema, or the request was rejected. Sink configuration mismatches, blob path missing, columns referenced that no longer exist, RU/s exceeded on Cosmos DB.

#### Credentials

The pipeline reached the auth layer and was rejected. Service principal secret expired, Key Vault key missing, OAuth token revoked, linked service authentication failed. These usually surface as a cluster: every pipeline that uses the same linked service breaks in the same hour.

#### Capacity

The data factory or one of its dependencies hit a quota or memory ceiling. ADF subscription quota exceeded, Cosmos DB request rate too large, the self-hosted IR ran out of memory mid-copy.

#### Gateway

The self-hosted integration runtime is the gateway between ADF and on-premises sources. When it cannot run a Java dependency, is saturated by concurrent tasks, or the Windows service is not running on the host, every pipeline routed through it fails until the gateway recovers.

#### Connectivity

The pipeline failed before it could exchange data with the source or sink. ODBC driver returned a network error, SAP RFC destination registration failed, the self-hosted IR cluster peer is unreachable.

#### Data format

The data reached the activity but the activity could not parse it. Usually a malformed query string, a column type mismatch in a schema-on-read sink, or an encoding issue in the source.

#### Permissions

The pipeline ran but a Windows or RBAC permission was missing. The most common variant is a self-hosted IR service account without permission to read a local share or write a managed folder.

MetricSign reads the Azure Data Factory activity log, pipeline run history, trigger run history, and integration runtime status. Where ADF Studio shows a generic "failed" status, MetricSign extracts the underlying error class and surfaces it in a single alert against the affected pipeline and its downstream consumers.

Four detection paths cover the majority of production incidents:

• Trigger-level failures. Caught from the trigger run history. A schedule trigger that never fired the pipeline produces no entry in the run log; MetricSign reads the trigger surface separately and alerts when an expected run did not start.
• Activity-level failures. Caught from the activity-level details inside each pipeline run. The alert names the pipeline, the activity, the UserError* class, and the linked downstream Power BI datasets, dbt models, or Fabric items that depend on it.
• Self-hosted integration runtime offline. Caught from the IR status endpoint. When an on-prem IR node flips offline because of UserErrorSelfHostedIntegrationRuntimeNotRunning or a JVM dependency error, MetricSign alerts before the next scheduled pipeline tries to use it.
• Linked service authentication failures. When a cluster of pipelines all return UserErrorLinkedServiceAuthenticationFailed or UserErrorOAuthTokenExpiredOrRevoked against the same linked service, the failures are grouped into one incident instead of paging on each pipeline separately.

Honest caveat: MetricSign reads what ADF exposes through its REST API. Errors that ADF logs only on the self-hosted IR host machine — a JVM install that succeeded but pointed at the wrong path, a Windows event log entry that never made it into the IR diagnostic upload — are not visible to MetricSign or to anything else outside the host. For those the diagnostic still happens on the IR machine itself.

When an ADF pipeline fails, work the diagnostic in this order rather than searching the message text:

1. Check the trigger log first. If the pipeline never started, the run log is empty. Open the trigger run history in ADF Studio Monitoring and confirm the schedule actually fired.
2. Read the error class, not the message. UserErrorAccessDenied and UnauthorizedAccessException both surface as "access denied" but require completely different fixes — one is a linked service credential, the other is a Windows ACL on the IR host.
3. Identify the category. Configuration, data source, credentials, capacity, gateway, connectivity, data format, permissions. The category determines who can fix it. The index above maps each code to its category.
4. Check whether it is one pipeline or many. A single pipeline returning UserErrorOAuthTokenExpiredOrRevoked is a per-pipeline credential issue. Every pipeline against the same linked service returning the same code in the same hour is a tenant- or subscription-level problem with that linked service or its key vault entry.
5. For self-hosted IR errors, check the IR host before the pipeline. Errors with HRESULT, DllNotFoundException, TypeInitializationException, OutOfMemoryException, or EndpointNotFoundException originate on the IR machine, not in ADF. Run the IR diagnostic on the host and check the Windows event log before changing anything in ADF Studio.
6. Match the timing to a deploy or a credential rotation. A burst of UserErrorLinkedServiceAuthenticationFailed at the same minute almost always lines up with a service principal secret expiring or a Key Vault rotation. A slow drift over a week is more likely a quota approaching its ceiling.

Skipping the category step is the most common mistake. Engineers Google the message text and end up reinstalling a JVM on an IR host when the actual fix was a Key Vault ACL.

Every code linked from this hub has its own page with the canonical Microsoft description, the typical pipeline scenario it appears in, and the fix steps. Use this list to jump directly to the code you are looking at.

This index covers the ADF errors with measurable search volume and reproducible fix paths. The full Microsoft reference lists more codes; the ones above are the codes that surface in production pipelines often enough to have their own dedicated page.

ADF failures should not surface first as a stale Power BI dashboard or a skipped dbt model. MetricSign monitors ADF triggers, activities, and integration runtime status across your subscriptions and routes the alert before the next downstream refresh starts.