Power BI refresh failures are easier to resolve when you diagnose them in a consistent order. This guide separates gateway availability, credentials, source changes, privacy settings, capacity, schedules, and query errors, then provides a recurring maintenance checklist and incident log you can use after every failed load.
Overview
A Power BI dataset refresh is a chain of dependencies rather than a single operation. Power BI must reach the data source, authenticate successfully, run the queries, apply transformations, load the model, and complete within the limits of the workspace and its capacity. A failure at any point can produce a message that appears broad or incomplete.
Start by identifying the refresh type. A cloud data source may connect directly from the Power BI service, while an on-premises source generally requires an on-premises data gateway. A refresh can also be initiated manually, run on a schedule, or be triggered through an automation process. The correct diagnosis depends on this context.
Before changing settings, record the dataset or semantic model name, workspace, source systems, last successful refresh, first failed refresh, refresh duration, and exact error text. Avoid repeatedly selecting Refresh now without recording results. Repeated attempts can obscure the original failure and make it harder to tell whether a change actually helped.
Power BI service labels and locations can change over time, and available options differ by workspace configuration and licensing. Use the current workspace, semantic model, gateway, and data source settings shown in your tenant rather than relying on an old screenshot or a menu path copied from another environment.
What to track
Use symptoms to narrow the likely cause
| Symptom or message pattern | Likely area to inspect | First practical check |
|---|---|---|
| Gateway is unreachable, offline, or unavailable | On-premises data gateway | Check the gateway service, host connectivity, cluster status, and whether the data source is mapped to the intended gateway connection. |
| Credentials are invalid, expired, or cannot be validated | Data source authentication | Open the dataset or semantic model settings and review stored credentials, authentication method, and the account's access to the source. |
| One query fails after a source change | Power Query steps or source schema | Open the query in Power Query and compare renamed, removed, or retyped columns with the steps that reference them. |
| Privacy or data-combination error | Privacy levels and query combinations | Review privacy settings for every involved source and confirm that the selected combination is appropriate for the organization's security requirements. |
| Refresh exceeds its allowed duration or capacity | Model size, query efficiency, and capacity | Compare the failed run's duration with normal runs, then inspect expensive queries, overlapping refreshes, and available capacity resources. |
| Scheduled refresh does not start | Schedule, ownership, or service configuration | Confirm the schedule is enabled, the time zone is understood, credentials are valid, and the model still has the required gateway or connection association. |
| Refresh succeeds but data appears stale | Source timing, incremental logic, or report cache | Verify that the source was updated before the refresh began and check filters, incremental refresh boundaries, and the model's reported completion time. |
Gateway and credential maintenance checklist
- Confirm the gateway host is powered on, connected to the network, and able to reach each required source.
- Keep the gateway installation on a supported, maintained version and review compatibility before planned upgrades.
- Document gateway clusters, their hosts, data source names, owners, and the datasets that depend on them.
- Review stored credentials after password rotations, account changes, certificate changes, or source migrations.
- Use a dedicated service identity where appropriate, with only the source permissions required for the data model.
- Check that the server name, database name, file path, or connection details match between Power BI Desktop and the Power BI service.
- Test one representative model after a gateway or credential change before treating the maintenance as complete.
Track the variables that explain recurring failures
For each important model, maintain a small record of normal refresh duration, expected completion window, source owner, gateway owner, credential owner, query dependencies, and business impact. Also record whether the model uses incremental refresh, combines multiple sources, or depends on a file or database location that may change.
Cadence and checkpoints
After every failed refresh
- Capture the exact error, timestamp, affected model, and refresh attempt identifier if the service provides one.
- Check whether other models using the same gateway, source, or credentials also failed.
- Determine whether the failure is new or part of a repeated pattern by comparing recent refresh history.
- Test the smallest relevant dependency first: gateway connectivity, credential validation, source access, then query execution.
- Make one controlled change, rerun a test, and record the result before making another change.
Monthly review
Once a month, review refresh history for models that support operational reporting. Look for gradually increasing duration, repeated retries, failures concentrated at a particular time, and schedules that overlap. Confirm that workspace ownership, gateway administrators, data source owners, and credential contacts are still accurate.
Use the review to identify models that are dependent on a single gateway host or an individual user's credentials. These are operational risks even when refreshes are currently succeeding. Document a recovery contact and a tested alternative wherever the business impact justifies it.
Quarterly or change-based review
Perform a deeper review at least quarterly and whenever a source, schema, gateway, identity, workspace, capacity arrangement, or licensing configuration changes. Recheck connector behavior and service settings after significant Power BI updates because labels, supported options, and connector capabilities may evolve.
Ask report owners whether refresh frequency still matches business need. A schedule that is too frequent can create unnecessary load, while a schedule that is too infrequent can make a report appear unreliable. Treat the schedule as part of the reporting design, not merely as an administrative setting.
How to interpret changes
A useful diagnostic separates shared failures from model-specific failures. If several models fail at the same time and use the same gateway, investigate the gateway, network, or common credentials first. If only one model fails, focus on its queries, schema, source permissions, and model-specific settings.
Timing is another important clue. A failure immediately after a source change points toward schema, permissions, or connection details. A failure that occurs after a normal period of success may indicate an expired credential, a changed password, a gateway update, a source outage, or a growing query workload. A failure that happens only during busy periods warrants a review of overlapping schedules and capacity pressure.
Do not assume that a successful gateway test proves the entire refresh will succeed. The test may confirm basic connectivity while the model still fails because a query references a missing column, combines sources with incompatible privacy settings, or requests more data than the available resources can process.
Likewise, do not treat a successful manual refresh as proof that the schedule is fixed. A manual run may use the current credentials and a different time window. Confirm the next scheduled run, its time zone, and whether the expected completion is visible in refresh history.
Refresh incident log template
Copy the following fields into your service desk, operations notebook, or reporting administration register:
- Date and time: Include the tenant or local time zone.
- Workspace and model: Record the exact names and environment.
- Refresh type: Manual, scheduled, incremental, or automation-triggered.
- Last successful refresh: Include its completion time and duration.
- Error text: Copy the full message rather than paraphrasing it.
- Shared dependencies: Gateway, data source, connector, credentials, and capacity where relevant.
- Investigation steps: Note each check and its result.
- Change made: Identify the setting, credential, query, or schedule changed.
- Validation: Record test results, the next scheduled run, and the person who confirmed recovery.
- Follow-up: Add a preventive action, owner, and review date if the issue could recur.
When to revisit
Return to this guide after every failed refresh until the cause is understood and the recovery is verified. Revisit it during a monthly gateway and credential review, before a planned source migration, and after changes to database schemas, file paths, authentication, workspaces, gateways, or capacity.
Schedule a quarterly health check for important models. Compare recent refresh duration with the established baseline, remove obsolete schedules, confirm ownership, and review whether alerts reach someone who can act. Refresh the documentation whenever a gateway cluster, connector, data source, or model dependency changes.
For the next incident, begin with three questions: What changed? What else is affected? What evidence confirms the fix? Answering them in order keeps Power BI refresh troubleshooting focused and creates a useful record for the next administrator. As your wider Microsoft environment changes, coordinate reporting reviews with operational runbooks such as the Azure Service Health and Status Guide and the Microsoft Teams Governance Review Checklist when shared ownership, outages, or governance processes affect reporting dependencies.
