Troubleshoot the on-premises data gateway

Note

We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback on this article, or the overall gateway docs experience, scroll to the bottom of the article.

This article discusses some common issues when you use the on-premises data gateway.

Note

If you encounter an issue that isn't listed here, create a support ticket for the particular cloud service that's running the gateway.

Update to the latest version

Issues can occur when the gateway version is out of date. It's a good general practice to make sure you're using the latest version. If you haven't updated the gateway for a month or longer, you might want to install the latest version of the gateway. Then see if you can reproduce the issue.

Inconsistent versions between gateway members in a cluster

Keep the versions of the gateway members in a cluster in sync. Having all the same version in a cluster helps to avoid unexpected refresh failures. These refresh failures might occur because the gateway member that a specific query is routed to might not be capable of executing it due to a lower version.

Troubleshoot common installation issues

Here are a few common installation issues and the resolutions that helped other customers.

Error: Failed to add user to group. (-2147463168 PBIEgwService Performance Log Users)

You might receive this error if you're trying to install the gateway on a domain controller. Deploying on a domain controller isn't supported. You need to deploy the gateway on a machine that isn't a domain controller.

Out-of-date antivirus software

You might encounter installation failures if the antivirus software on the installation machine is out of date. You can either update the antivirus installation or disable the antivirus software only for the duration of the gateway installation. After the installation is finished, reenable the antivirus software.

Same or older gateway version

You might come across the following error if you try to install the same version or a previous version of the gateway compared to the one that you already have.

Gateway installation error

Troubleshoot configuration

Firewall or proxy

To test if the gateway has access to all the required ports, run the network ports test. The results of the test are either Completed (Succeeded) or Completed (Failed, see last test results). If the test succeeded, your gateway successfully connected to all the required ports. If the test failed, your network environment might be blocking these required ports and servers.

For information on how to provide proxy information for your gateway, see Configure proxy settings for the on-premises data gateway.

A firewall also might be blocking the connections that the Azure Service Bus makes to the Azure data centers. If that's the case, unblock the IP addresses for your region for those data centers. You can get a list of Azure IP addresses from this website. To find the current data center region you're in, see Set the data center region.

Authentication to proxy server

Your proxy might require authentication from a domain user account. By default, the gateway uses a Service SID for the Windows service sign-in user. Changing the sign-in user to a domain user can help with this situation. For more information, see Change the gateway service account to a domain user.

Your proxy only allows ports 80 and 443 traffic

Some proxies restrict traffic to only ports 80 and 443. By default, communication to Azure Service Bus occurs on ports other than 443.

You can force the gateway to communicate with Azure Service Bus by using HTTPS instead of direct TCP.

Common errors

Error: Failed to create a gateway. Try again.

This error could be due to proxy configuration issues. The gateway log provides additional details for troubleshooting. For more information, see Configure proxy settings for the on-premises data gateway.

Error: Power BI service reported local gateway as unreachable. Restart the gateway and try again.

At the end of configuration, the Power BI service is called again to validate the gateway. The Power BI service doesn't report the gateway as live. Restarting the Windows service might allow the communication to be successful. To get more details, collect and review the logs, as described in the following section.

Troubleshooting tools

Collect logs from the on-premises data gateway app

There are several logs you can collect for the gateway, and you should always start with the logs. The simplest way to collect logs after you install the gateway is through the on-premises data gateway app. In the on-premises data gateway app, select Diagnostics and then select the Export logs link, as shown in the following image.

On-premises data gateway app logs

This file is saved to the ODGLogs folder on your Windows desktop in .zip format.

Event logs

To find the event logs for the on-premises data gateway service, follow these steps:

  1. On the computer with the gateway installation, open the Event Viewer.

  2. Expand Event Viewer > Applications and Services Logs.

  3. Select On-premises data gateway service.

On-premises data gateway event logs

Next steps