Foutmeldingen in Azure Data Factory-pipelines: een overzicht van veelvoorkomende fouten

Een ADF-fout blijft zelden beperkt tot ADF. De meeste productie pipelines zijn bedoeld om data te plaatsen in een laag die door iets anders wordt gelezen – een Power BI Direct Lake-datacenter waar data uit wordt gelezen, een Fabric-datawarehouse waar een dbt-project data transformeert, of een Snowflake-tabel waar een downstream BI-dataset van afhankelijk is.

Drie cascade-patronen dekken de meeste incidenten die datateams afhandelen:

De stille laadactie met nul rijen. Een copy activity wordt zonder fouten voltooid, maar schrijft nul rijen omdat een bronfilter is gewijzigd, een partitie leeg is of een UserErrorInvalidColumnReferenced-fout is onderschept en genegeerd door een OnError-activiteit. Power BI vernieuwt de lege tabel met succes. Het dashboard toont de gecachede data van gisteren omdat Direct Lake is teruggevallen. Niemand wordt hierover geïnformeerd.

De vertraagde maar voltooide pipeline. De ADF-pipeline duurt 22 minuten langer dan de basistijd omdat de self-hosted integration runtime de foutmelding UserErrorSelfHostedIntegrationRuntimeBusyWithFullTask kreeg en de uitvoering in de wachtrij plaatste. De pipeline slaagt, maar eindigt nadat de Power BI verversing van 06:00 uur al is gestart. De verversing leest de momentopname van de vorige dag en het rapport van maandag toont de cijfers van vorige week.

De fout met de downstream-referenties. De pipeline mislukt met de foutmelding UserErrorOAuthTokenExpiredOrRevoked tegen een linked service. Het dbt-project dat downstream wordt uitgevoerd, ziet geen nieuwe partitie en slaat het model met een actualiteitscontrole over, wat correct gedrag is, maar geen waarschuwing genereert. Zes uur later merkt iemand het op.

In alle drie de gevallen is de ADF-fout zelf binnen enkele minuten te herstellen – zodra je hem vindt. De schade zit hem in de tijd tussen de fout en het moment dat iemand de waarschuwing ziet.

Voor een volledig overzicht van hoe ADF, Databricks, dbt en Power BI op elkaar aansluiten, zie end-to-end data lineage from ADF to Power BI.

ADF-fouten vallen onder een aantal foutmodi. Gebruik deze index om te bepalen met welk type probleem je te maken hebt en klik vervolgens door naar de pagina met de oplossing voor de betreffende code.

#### Configuratie (meest voorkomend)

Deze fouten treden op wanneer de configuratie van de pipeline definitie, de linked service of de self-hosted integration runtime onjuist is. Problemen met tenants, ontbrekende assemblies, een niet-geïnstalleerde JVM of niet-toegekende ACL's. Vaak voorkomend na IR-upgrades of tenantmigraties.

#### Gegevensbron

De pipeline heeft de bron of bestemming bereikt, maar er is iets misgegaan met de gegevens, het schema of het verzoek. Configuratie van de bestemming komt niet overeen, blobpad ontbreekt, er wordt verwezen naar kolommen die niet meer bestaan, RU/s overschreden op Cosmos DB.

#### Referenties

De pipeline bereikte de authenticatielaag en werd geweigerd. Service principal secret is verlopen, Key Vault-sleutel ontbreekt, OAuth-token ingetrokken, authenticatie van linked service mislukt. Deze fouten treden meestal op als een cluster: elke pipeline die dezelfde linked service gebruikt, loopt binnen hetzelfde uur vast.

#### Capaciteit

De datafactory of een van de afhankelijkheden ervan heeft een quotum of geheugenlimiet bereikt. ADF-abonnementsquotum overschreden, Cosmos DB-aanvraagsnelheid te hoog, de zelfgehoste IR heeft tijdens het kopiëren geen geheugen meer.

#### Gateway

De self-hosted integration runtime is de gateway tussen ADF en on-premise bronnen. Wanneer deze een Java-afhankelijkheid niet kan uitvoeren, overbelast is door gelijktijdige taken of de Windows-service niet actief is op de host, mislukt elke pipeline die erdoorheen loopt totdat de gateway is hersteld.

#### Connectiviteit

De pipeline is mislukt voordat er gegevens konden worden uitgewisseld met de bron of bestemming. Het ODBC-stuurprogramma heeft een netwerkfout geretourneerd, de SAP RFC-bestemmingsregistratie is mislukt, de peer van het zelfgehoste IR-cluster is onbereikbaar.

#### Gegevensindeling

De gegevens bereikten de activiteit, maar de activiteit kon ze niet parseren. Meestal komt dit door een onjuist geformuleerde queryreeks, een mismatch in kolomtypen in een schema-on-read-sink of een coderingsprobleem in de bron.

#### Machtigingen

De pipeline is uitgevoerd, maar er ontbrak een Windows- of RBAC-machtiging. De meest voorkomende variant is een zelfgehost IR-serviceaccount zonder toestemming om een lokale share te lezen of een beheerde map te schrijven.

MetricSign leest het activity log van Azure Data Factory, de uitvoeringsgeschiedenis van pipelines, de uitvoeringsgeschiedenis van triggers en de runtime-status van integraties. Waar ADF Studio een algemene status 'mislukt' weergeeft, extraheert MetricSign de onderliggende foutklasse en toont deze in één waarschuwing voor de betreffende pipeline en de daaraan gekoppelde afnemers.

Vier detectiepaden dekken de meeste incidenten in productieomgevingen:

• Fouten op trigger niveau. Deze worden gedetecteerd in de uitvoeringsgeschiedenis van triggers. Een geplande trigger die de pipeline nooit heeft uitgevoerd, genereert geen vermelding in het run log; MetricSign leest de trigger gegevens afzonderlijk en geeft een waarschuwing wanneer een verwachte uitvoering niet is gestart.

• Fouten op activiteitsniveau. Deze worden gedetecteerd in de details op activiteitsniveau binnen elke pipeline run. De waarschuwing vermeldt de pipeline, de activiteit, de UserError*-klasse en de gekoppelde Power BI datasets, dbt-modellen of Fabric-items die ervan afhankelijk zijn.

• Self-hosted integration runtime offline. Deze melding wordt opgevangen via het IR-status-endpoint. Wanneer een on-premise IR-node offline gaat vanwege UserErrorSelfHostedIntegrationRuntimeNotRunning of een JVM-afhankelijkheidsfout, geeft MetricSign een waarschuwing voordat de volgende geplande pipeline deze probeert te gebruiken.

• Authenticatiefouten voor linked services. Wanneer een cluster van pipelines allemaal UserErrorLinkedServiceAuthenticationFailed of UserErrorOAuthTokenExpiredOrRevoked retourneert voor dezelfde linked service, worden de fouten gegroepeerd in één incident in plaats van dat elke pipeline afzonderlijk wordt gepagineerd.

Eerlijke kanttekening: MetricSign leest de gegevens die ADF via de REST API beschikbaar stelt. Fouten die ADF alleen registreert op de zelfgehoste IR-hostmachine — een JVM-installatie die weliswaar is gelukt, maar naar het verkeerde pad verwees, een Windows-gebeurtenislogboekvermelding die nooit in de IR-diagnostische upload is opgenomen — zijn niet zichtbaar voor MetricSign of voor andere systemen buiten de host. Voor deze fouten vindt de diagnose nog steeds plaats op de IR-machine zelf.

Als een ADF-pipeline mislukt, doorloop dan de diagnose in deze volgorde in plaats van de berichttekst te doorzoeken:

1. Controleer eerst het trigger log. Als de pipeline nooit is gestart, is het run log leeg. Open de trigger uitvoeringsgeschiedenis in ADF Studio Monitoring en controleer of de planning daadwerkelijk is uitgevoerd.

1. Lees de foutklasse, niet het bericht. UserErrorAccessDenied en UnauthorizedAccessException worden beide weergegeven als "toegang geweigerd", maar vereisen volledig verschillende oplossingen: de ene betreft een linked service referentie, de andere een Windows ACL op de IR-host.

1. Identificeer de categorie. Configuratie, gegevensbron, referenties, capaciteit, gateway, connectiviteit, gegevensindeling, machtigingen. De categorie bepaalt wie het probleem kan oplossen. De bovenstaande index koppelt elke code aan de bijbehorende categorie.

1. Controleer of het om één pipeline of meerdere gaat. Een enkele pipeline die UserErrorOAuthTokenExpiredOrRevoked retourneert, is een referentieprobleem per pipeline. Elke pipeline die dezelfde linked service op hetzelfde uur uitvoert en dezelfde code retourneert, duidt op een probleem op tenant- of abonnementsniveau met die linked service of de bijbehorende Key Vault-vermelding.

1. Controleer bij zelfgehoste IR-fouten de IR-host vóór de pipeline. Fouten met HRESULT, DllNotFoundException, TypeInitializationException, OutOfMemoryException of EndpointNotFoundException ontstaan op de IR-machine, niet in ADF. Voer de IR-diagnose uit op de host en controleer het Windows-gebeurtenislogboek voordat je iets wijzigt in ADF Studio.

1. Stem de timing af op een implementatie of een referentierotatie. Een golf van UserErrorLinkedServiceAuthenticationFailed in dezelfde minuut valt bijna altijd samen met het verlopen van een service principal secret of een Key Vault-rotatie. Een langzame afwijking over een week duidt eerder op een quotum dat de limiet nadert.

Het overslaan van de categoriestap is de meest voorkomende fout. Technici googelen de foutmelding en installeren uiteindelijk een JVM opnieuw op een IR-host, terwijl de daadwerkelijke oplossing een Key Vault ACL was.

Elke code waarnaar vanuit deze hub wordt verwezen, heeft een eigen pagina met de standaard Microsoft-beschrijving, het typische pipeline-scenario waarin deze voorkomt en de stappen voor het oplossen van het probleem. Gebruik deze lijst om direct naar de code te gaan die je zoekt.

Deze index behandelt ADF-fouten met een meetbaar zoekvolume en reproduceerbare oplossingspaden. De volledige Microsoft-referentie bevat meer codes; de bovenstaande codes komen vaak genoeg voor in productie pipelines om een eigen pagina te rechtvaardigen.

ADF-fouten zouden niet als eerste moeten verschijnen in de vorm van een verouderd Power BI dashboard of een overgeslagen dbt-model. MetricSign bewaakt ADF-triggers, -activiteiten en de runtime-status van integraties in al je abonnementen en stuurt de waarschuwing door voordat de volgende downstream-refresh start.