1. Read the refresh history
Workspace → semantic model → Refresh history → Show next to the failed attempt. Match the message:
| Message | Cause |
|---|---|
The credentials provided for the X source are invalid | Password changed or OAuth token expired |
Unable to connect to the data source / The gateway is offline | Gateway service stopped, or the machine is off |
You can't schedule refresh for this semantic model because ... data sources are missing a gateway configuration | The source in the .pbix doesn't match any gateway connection |
Timeout expired / refresh cancelled after 2 hours | Over the limit (2 h on shared capacity, 5 h on Premium) |
Memory error: ... exceeded the available memory | Model too big for the capacity during refresh |
2. Credentials
Semantic model → Settings → Data source credentials → Edit credentials. For service accounts, use one whose password doesn't expire, or a service principal where the source supports it.
3. Gateway
On the gateway machine:
- Open the on-premises data gateway app → Status, and Diagnostics → Network ports test.
- Check the Windows service PBIEgwService is running.
- Gateway logs:
C:\Windows\ServiceProfiles\PBIEgwService\AppData\Local\Microsoft\On-premises data gateway\. - Keep the gateway updated; Microsoft supports only recent releases.
The gateway needs outbound access to Azure Service Bus and Power BI endpoints (TCP 443; 5671–5672 and 9350–9354 if not forced to HTTPS). A new proxy or firewall rule often causes "gateway offline".
4. Data source definition mismatch
The server and database names in Power Query must match the gateway connection exactly: sqlprod01 ≠ sqlprod01.contoso.local ≠ 10.1.2.3. Fix the name in Power Query, or add a connection that matches. Then in Settings → Gateway and cloud connections, map the source.
5. Timeouts and memory
- Turn on incremental refresh for large fact tables, so only recent partitions refresh.
- Remove unused columns, especially high-cardinality text and date-times.
- Make sure query folding works: right-click the last step in Power Query → View Native Query. If it's greyed out, the transformations run in the gateway, not the database.
- For huge models, use a larger capacity or move to Direct Lake / DirectQuery where appropriate.
6. Get alerted
In the refresh schedule, set Send refresh failure notifications to the model owner and a support mailbox, so the team knows before the customer opens the report.
Tip
Run two or more gateway members in a cluster. Updating or rebooting one machine then doesn't break every scheduled refresh in the company.