Foutmeldingen in Power BI Gateway: uitleg van DM_GWPipeline-codes

Gatewayfouten hebben een eigenschap die ze storender maakt dan de meeste Power BI storingen: wanneer er één fout optreedt, vertegenwoordigt deze meestal meerdere datasets die tegelijkertijd uitvallen. Alle datasets die via de betreffende gateway lopen, vallen tegelijk uit – niet één voor één en niet in willekeurige volgorde. Als tien datasets een gateway delen en de gateway offline gaat, verschijnen er tien refresh fouten tegelijk in je incidentenoverzicht.

Deze gelijktijdigheid is eigenlijk diagnostische informatie. Een cluster van refresh fouten in datasets die niets met elkaar gemeen hebben behalve hun gateway, is vrijwel zeker een gateway probleem, geen probleem per dataset. De DM_GWPipeline-foutcodes zijn de manier waarop de gateway aangeeft wat voor soort gateway probleem het is.

De foutcodes vallen in twee groepen: fouten met betrekking tot de verbinding tussen Power BI Service en de gateway zelf (de cloud-naar-gateway-verbinding) en fouten met betrekking tot de verbinding tussen de gateway en de gegevensbron (de gateway-naar-gegevensverbinding). De oplossingsrichting is voor elke groep verschillend.

GatewayUnreachable is een verbindingsfout tussen de cloud en de gateway. De Power BI service heeft een refresh verzoek naar het gateway cluster verzonden en geen reactie ontvangen. De gateway is vanuit je perspectief niet offline: de Windows-service is mogelijk actief, de machine is ingeschakeld en de gegevensbron is toegankelijk. De Service Bus-relaisverbinding die Power BI gebruikt om met de gateway te communiceren, is echter verbroken.

Veelvoorkomende oorzaken: de Windows-service van de gateway is gestopt (vaak stilzwijgend na een Windows-update die een herstart vereiste, maar de service niet automatisch opnieuw startte); uitgaand verkeer van de gateway machine naar Azure Service Bus (*.servicebus.windows.net op poort 443 of 5671) is geblokkeerd door een wijziging in een firewall regel; de gateway registratie is ongeldig geworden na een wijziging van de machinenaam of het domein.

Oplossing: open de toepassing voor de on-premise data gateway op de gateway machine. Als deze offline wordt weergegeven, bevestigt dit het probleem. Controleer de Windows Services-console en controleer of de gateway service is gestart. Als de service actief is, maar de gateway nog steeds offline wordt weergegeven, start je deze opnieuw en wacht je twee tot drie minuten totdat de Service Bus-verbinding opnieuw tot stand is gebracht. Voor netwerkgerelateerde blokkeringen kun je de verbindingsdiagnose uitvoeren via het tabblad Status van de gateway-app en de uitgaande firewall regels voor *.servicebus.windows.net controleren.

De foutmelding MashupDataAccessError duidt op een probleem met de verbinding tussen de gateway en de gegevensbron. De gateway heeft het refresh verzoek van Power BI ontvangen, maar bij het opvragen van de gegevensbron is dit mislukt. De verbinding tussen de cloud en de gateway werkt wel; het probleem zit tussen de gateway machine en de database- of bestandsserver.

Dit is de meest voorkomende DM_GWPipeline-fout in productieomgevingen. Veelvoorkomende oorzaken: de in de gateway opgeslagen referenties zijn verlopen of gereset (de gateway gebruikt een aparte referentieopslag dan Power BI Service; referenties moeten op beide plaatsen worden bijgewerkt); de gegevensbronserver is tijdelijk niet beschikbaar of de hostnaam is gewijzigd; een netwerkbeleid of firewall regel op het lokale netwerk van de gateway machine blokkeert uitgaande verbindingen naar de bronhost.

Oplossing: ga in Power BI Service naar Instellingen → Gateways beheren en voer de referenties voor de betreffende gegevensbron opnieuw in. Zelfs als ze correct lijken, zorgt het opnieuw invoeren voor een hercontrole en lost dit vaak tijdelijke problemen met de referentiecache op. Meld je vervolgens aan bij de gateway machine en test de verbinding met de bron rechtstreeks (ping, telnet of SSMS voor SQL-bronnen). Controleer de Windows-gebeurtenislogboeken op de gateway machine onder Toepassingslogboeken, bron: On-premises data gateway, voor aanvullende foutdetails die niet door Power BI Service worden weergegeven.

De on-premise data gateway maakt verbinding met Power BI Service via Azure Service Bus. Dit is een permanente relay-verbinding die moet worden onderhouden om de gateway refresh taken te kunnen laten ontvangen. Wanneer deze verbinding mislukt, is de gateway feitelijk offline, zelfs als de gateway-machine actief is en de gegevensbron toegankelijk is.

Dit is iets anders dan GatewayUnreachable. GatewayUnreachable is de foutmelding vanuit het perspectief van Power BI: de gateway is niet bereikbaar. ServiceBusCommunicationException is een foutmelding van de gateway zelf, die verschijnt wanneer deze probeert de Service Bus-verbinding te onderhouden en daarin faalt.

Veelvoorkomende oorzaken: een firewall regel die uitgaande HTTPS (poort 443) of AMQP (poort 5671/5672) vanaf de gateway-machine blokkeert; een proxyserver die TLS-verbindingen onderschept en beëindigt voordat ze Azure bereiken; antivirus- of endpointbeveiligingssoftware die de netwerkoproepen van het gateway-proces blokkeert.

Oplossing: open de gateway-app op de gateway-machine en controleer de verbindingsstatus. Als deze 'Verbroken' aangeeft, voer je de verbindingstest uit in het gedeelte Diagnostiek. Deze test specifiek of de Service Bus-endpoints bereikbaar zijn. Als er een proxy in gebruik is, configureer je de proxy-instellingen in het gateway-configuratiebestand (Microsoft.PowerBI.DataMovement.Pipeline.GatewayCore.dll.config). Door de antivirussoftware op de gateway-machine tijdelijk uit te schakelen en te testen of de verbinding is hersteld, kun je bevestigen of endpointbeveiliging de oorzaak is.

Deze fout is ongebruikelijker dan de andere. Power BI heeft een refresh job naar de wachtrij van de gateway verzonden, maar toen de verwerkingsengine deze wilde ophalen, was de job verdwenen. De spool, de tijdelijke wachtrij voor verzonden refresh taken, verloor de bewerking voordat deze kon worden uitgevoerd.

De meest voorkomende oorzaak is een herstart van de gateway service tussen het moment van verzending en de uitvoering van de job. Als de gateway service opnieuw is opgestart (vanwege een Windows-update, een antivirusactie of een crash) nadat Power BI de job in de wachtrij had geplaatst, maar voordat de gateway de job begon te verwerken, gaat de job verloren. Een reconnect met Service Bus kan ook lopende bewerkingen verbreken.

Oplossing: start onmiddellijk een handmatige refresh. Deze fout is bijna altijd tijdelijk en de refresh slaagt bij een nieuwe poging. Als de fout zich opnieuw voordoet, controleer dan het Windows-gebeurtenislogboek op de gateway machine op gebeurtenissen met betrekking tot het opnieuw opstarten van services rond het tijdstip van de fouten. De hoofdoorzaak is meestal instabiliteit van de gateway: de service wordt opnieuw opgestart, crasht of wordt beëindigd door een extern proces. Werk de gateway bij naar de nieuwste versie (Microsoft brengt maandelijks updates uit en pakt regelmatig de betrouwbaarheid van de spooling aan), zorg ervoor dat de gateway machine niet wordt opgenomen in het patch-/herstartschema tijdens geplande refresh vensters en controleer de beveiligingslogboeken van het endpoint op gebeurtenissen met betrekking tot het beëindigen van processen.

DM_GWPipeline_Gateway_UnknownError is de algemene foutcode van de gateway. Deze wordt geactiveerd wanneer de gateway de fout niet aan een specifiekere categorie kan toewijzen, meestal omdat het gateway proces is vastgelopen, is beëindigd door beveiligingssoftware of een resource (geheugen, schijf) niet meer beschikbaar is tijdens de verwerking.

In tegenstelling tot de meeste gateway fouten, duidt deze niet altijd op een configuratieprobleem. Een geheugenoverloop tijdens het refreshen van een grote dataset, een volle schijf in de werkmap van de gateway machine of een bug in de geïnstalleerde gateway versie kunnen allemaal deze code veroorzaken zonder dat er een netwerk- of aanmeldingsprobleem is.

Oplossing: controleer de Windows Logboeken op de gateway machine op crashmeldingen op het moment van de fout. Raadpleeg de log bestanden van de gateway zelf (meestal in %LocalAppData%\Microsoft\On-premises data gateway\) voor de foutdetails die de algemene code verbergt. Zorg ervoor dat de gateway machine ten minste enkele GB vriu schijfruimte heeft. Als de fout zich af en toe voordoet en samenvalt met grote datasetrefreshen, kan het toevoegen van geheugen aan de gateway-VM of het spreiden van gelijktijdige refreshen de geheugenbelasting verminderen die deze fout vaak veroorzaakt.

Let op het subtiele verschil: DM_GWPipeline_UnknownError (zonder _Gateway_) is een aparte fout van de algemene gateway fout hierboven. Deze fout omvat bijna altijd een CryptographicException, het SAML-ondertekeningscertificaat of Kerberos-certificaat dat voor SSO wordt gebruikt, is niet toegankelijk voor het gateway-serviceaccount.

Deze fout treedt specifiek op in omgevingen die SAML-gebaseerde SSO of Kerberos-gedelegeerde toegang via de gateway gebruiken. De SSO-configuratie vereist een certificaat waarvan de privésleutel door het gateway-serviceaccount moet kunnen worden gelezen. Als de machtigingen van het serviceaccount voor die certificaatsleutel verloren gaan, bijvoorbeeld na een certificaatrefresh waarbij de sleutelmachtigingen niet zijn overgenomen, mislukt elke SSO-gebaseerde refresh met deze foutcode.

Oplossing: controleer het volledige gateway logboek. De velden InnerType en InnerMessage in de logboekvermelding bevatten de daadwerkelijke fout die door de algemene code wordt omvat. Als InnerType CryptographicException is, controleer dan of het SAML- of Kerberos-certificaat in het juiste certificaatarchief op de gateway machine is geïnstalleerd en of het gateway serviceaccount leesrechten heeft voor de privésleutel (gebruik certlm.msc → klik met de rechtermuisknop op het certificaat → Privésleutels beheren). Voer de wizard voor SSO-configuratie van de gateway opnieuw uit nada je toegang tot de sleutel hebt verleend en start de gateway service opnieuw.

MetricSign groepeert gateway-gerelateerde fouten op basis van het gateway cluster, niet op basis van de datasets die ze betreffen. Eén incident omvat alle datasets die tegelijkertijd zijn uitgevallen, toont ze in de detailweergave en bevat de gateway foutcode en de laatst bekende gatewaystatus. De engineer ziet direct de omvang van het probleem en start de gateway reparatie – in plaats van tien afzonderlijke onderzoeken per dataset.