Back to Blog

Troubleshooting the Power BI On-Premises Data Gateway - Field-Tested Fixes

May 22, 2026•10 min read•Michael Ridland

The Power BI on-premises data gateway is one of those bits of infrastructure that sits quietly doing its job for months, then breaks at the worst possible moment with an error message that tells you almost nothing. I've spent more late nights debugging gateway issues than I care to admit, and after a while you start to recognise the same handful of failure patterns.

Microsoft has a reasonable troubleshooting article but it's organised the way the engineers think about it, not the way you encounter problems. This post is organised the way you actually hit these issues: someone reports a broken report at 8am, you need to figure out what's wrong, and you don't have all day.

Before any of the rest of this matters, check your gateway version. Microsoft ships monthly updates and a huge chunk of the connectivity and reliability fixes happen in those releases. If the gateway you're debugging is more than three months old, upgrade it first and see if the problem persists. Don't waste an hour debugging a bug that was fixed in the version you haven't installed yet.

The "configured but not reachable" puzzle

Right at the end of gateway setup, Power BI calls back to validate connectivity. Sometimes the service reports the gateway as unreachable even though everything looks fine. The user has filled in all the fields. The "test connection" button worked. Yet the service stubbornly insists it can't talk to the gateway.

Nine times out of ten, restarting the on-premises data gateway service on the host machine fixes this. Open Services.msc, find the gateway service, restart it. Try the validation again. This isn't a satisfying fix but it works often enough that I do it first now before digging further.

If a restart doesn't help, the gateway logs are your friend. There's a specific collection process Microsoft documents and the logs tell you exactly which call is failing. We've seen cases where corporate proxies were silently dropping the gateway's outbound traffic, cases where the gateway service account had been removed from a group it needed, and cases where Azure Relay endpoints were being blocked by upstream firewall rules nobody knew about. Without the logs, you're guessing.

Bring-your-own Azure Relay limitations

If your security team has insisted on Bring Your Own Azure Relay (BYO Relay), and the gateway suddenly can't talk to the Power BI service, check whether Private Link has been enabled on that Relay namespace. The gateway's BYO Relay support doesn't currently work with Private Link. You either need to disable Private Link on the Relay, or revert to the default managed Relay configuration.

This is one of those situations where the security team and the data team need to have a conversation. Private Link on Azure Relay sounds like good security hygiene, and it is, but the gateway just can't work with it yet. Have the conversation early before it becomes a production incident.

"Invalid connection credentials" - the most common error

This is far and away the message you'll see most often, and it almost always means exactly what it says. The credentials stored in the gateway don't work against the data source.

When debugging this, click Show Details. The actual error message from the underlying data source is there. For SQL Server you'll see something like "Login failed for user 'username'". For Oracle you'll see Oracle's own error format. The underlying error tells you what specifically is wrong.

Things to actually check:

  • Has the password been rotated? In environments with regular password rotation policies, gateway credentials drift out of sync because nobody updates them when AD passwords change. We had a client where every report broke at the same time every 90 days because of this exact issue. Solved it with a documented runbook tied to the password rotation calendar.
  • Are you using the right authentication mode? SQL Server can authenticate with Windows or SQL credentials. The dropdown in the gateway config has to match what the SQL instance actually accepts. If you're using a SQL account but the gateway is set to Windows auth, you get this error.
  • Does the account have permission? Just because the credentials are valid for login doesn't mean they have permission on the database you're trying to query.

The other variant of this error is "Cannot connect to the database". Same underlying issue but in this case the login was accepted at the server level but rejected at the database level. Check that the user has actual permissions on the specific database, not just the server.

"Unknown error in data gateway"

This is the unhelpful one. Power BI tells you something went wrong but won't tell you what. The error code is DM_GWPipeline_UnknownError which doesn't help at all.

When you see this, get onto the gateway host machine and check Windows Event Viewer. Specifically: Applications and Services Logs > On-premises data gateway Service. The actual error message will be there, with stack traces and everything.

Common things we've seen behind this error:

  • The data source server is genuinely down or unreachable from the gateway host.
  • DNS resolution from the gateway host doesn't match what was used in Power BI. Common when the gateway is on a different network segment than the developer who configured the report.
  • The gateway host has no outbound DNS at all because someone tightened firewall rules.
  • A driver mismatch. The gateway includes its own ODBC and OLE DB drivers but if you're connecting to something exotic, you might need an additional driver installed on the gateway host.

The fix depends on the underlying cause. Event Viewer is the only way to know which it is.

The TGGAU attribute saga

This is the one that catches new gateway admins out, and it's particular to Analysis Services. You'll see an error along the lines of "The username or password is incorrect" even when you know the credentials are right.

The actual problem is that the service account running Analysis Services needs the Token-Groups-Global-And-Universal (TGGAU) directory attribute. This attribute is enabled by default on domains that support pre-Windows 2000 compatibility access. Modern Active Directory domains usually don't have this enabled.

To check if this is your problem, use dsacls from a domain controller against the user's distinguished name:

dsacls "CN=John Doe,CN=UserAccounts,DC=contoso,DC=com"

You're looking for output that includes:

Allow BUILTIN\Windows Authorization Access Group
                                SPECIAL ACCESS for tokenGroupsGlobalAndUniversal
                                READ PROPERTY

If that block is missing, you've found your problem. The fix is to enable TGGAU on the Analysis Services service account. Your AD team will know how to do this. It's a Group Policy thing or can be done via ADSI Edit.

The other variant of "username or password is incorrect" with Analysis Services is when AS is in a different AD domain from the Power BI users, and there's no two-way trust. Get your domain admins involved because this isn't fixable from the Power BI side.

I'd estimate we hit one of these two Analysis Services authentication issues at maybe one in five gateway deployments for Power BI work we do for larger enterprises. Worth knowing about because it sounds like a credential problem when it's actually an AD configuration problem.

"EffectiveUserName is not valid"

If you're seeing the very specific error about EffectiveUserName, the account configured in the gateway for Analysis Services isn't a server admin on the AS instance. EffectiveUserName impersonation requires the connecting account to have admin rights on AS.

The fix is to either grant the gateway account server admin on Analysis Services (often unpalatable for security reasons), or to switch your model to use a different authentication mode that doesn't require impersonation. Row-level security implemented in the model layer with USERPRINCIPALNAME() is one option. Direct token passthrough is another for newer setups.

We tend to recommend RLS at the model layer for most clients because it's cleaner and doesn't require giving the gateway account elevated privileges. Bit more work upfront but much easier to maintain.

"You don't have any gateway installed"

This error usually means one of three things.

The data source you're using in the report doesn't have a matching definition in any gateway. Add the data source through the Manage connections and gateways portal first, then try again.

Your browser has cached an old view of the available gateways. Clear the cache or sign out and back in. Sounds dumb but it's the fix maybe 20% of the time.

The data source definitions in your gateway don't match what's in the report. The gateway needs an entry for every distinct connection string used in the report. If you used mydb.company.com.au in the report but the gateway has mydb.company.com.au:1433, those don't match. Get the strings byte-identical or use the matching options in the gateway settings.

This last one is the most insidious. Power BI is strict about matching connection strings between report and gateway. We've seen reports built against tcp:server.example.com.au,1433 that wouldn't bind to a gateway with just server.example.com.au configured, even though they were semantically the same destination. Be deliberate and consistent about how connection strings are written.

"Credentials are invalid" when you know they're not

This is one of the most maddening problems. The semantic model refreshes without errors. The connection works. But Power BI's UI shows a banner saying credentials are invalid. When you try to re-enter the same correct credentials, you get a popup error saying they're invalid.

This is usually a gateway test connection issue, not a real credential issue. When you save credentials through the Power BI service, the service makes the gateway do a test connection right then and there. If the test connection fails for any reason (DNS timeout, slow handshake, transient network issue), the service marks the credentials as invalid even though they're fine.

Things that have worked for us:

  • Retry the save during off-peak hours when the network isn't congested.
  • Update credentials through the gateway's own configuration UI on the host machine instead of through the Power BI service.
  • Check that there's no proxy interfering with the test connection.
  • Verify the gateway host's outbound connectivity to the data source is healthy at the moment of the credential save.

If the problem is intermittent, it's almost always network-related. If it's consistent, look at firewall and DNS first.

A few patterns that prevent future grief

Things we do for clients that head off most of these problems:

Document gateway data source definitions outside the gateway. Run a process every week that exports your gateway data source configuration to a text file in source control. When something breaks, you can see what changed.

Monitor the gateway from outside the gateway. Set up a synthetic monitor that tries to refresh a tiny dummy semantic model every 15 minutes. If it fails, you know about the problem before users do. We've used Azure-based monitoring hooks for this with most clients.

Run two gateways in a cluster. Single-gateway setups become incidents waiting to happen. Run two in a cluster. The cost is small. The resilience benefit is huge.

Keep the gateway host machine boring. No other software. No other services. No file shares. No application servers sharing the box. The gateway is fussy about resource contention and you don't want any other workload competing with it. Dedicated VM, locked-down config, regular patching.

Patch monthly. As mentioned at the top, monthly gateway updates fix real bugs. Treat gateway patching with the same discipline as patching your SQL servers.

When to ask for help

If you've worked through the obvious things and you're still stuck, gateway issues can spiral into deep AD, network, and Azure debugging territory. We've taken on jobs from teams who'd been chasing a gateway issue for a week before they called. It's almost always faster to bring in someone who's seen the failure mode before than to keep grinding.

That's the kind of work our Power BI consulting team handles regularly across Sydney, Melbourne, Brisbane and the rest of Australia. We've seen most of the failure modes at this point and can usually pattern-match to a fix quickly. If you'd like a hand, get in touch.

Reference: Troubleshoot on-premises data gateways - Microsoft Learn