Power BI: Reports, Datasets, Gateways, and Sharing Best Practices
Why Power BI Sharing Problems Are So Common
I've seen this exact situation on dozens of enterprise deployments: someone builds a beautiful Power BI report, hits "Share," and then spends the next two hours fielding "I can't see the data" messages from colleagues. Power BI sharing best practices are not obvious , the platform has several overlapping sharing mechanisms, each designed for a different scenario, and picking the wrong one causes cascading permission failures that are genuinely confusing to diagnose.
The core issue is that Power BI distinguishes sharply between sharing a report, sharing an app, and sharing a semantic model (what used to be called a dataset). These are three separate objects with three separate permission models. When you share only the report but forget to give the recipient access to the underlying semantic model, they hit a blank screen or a data-access error , even though you technically "shared" the file with them.
Add workspaces, gateway configurations, and the possibility that your recipient might be in a completely different Azure Active Directory tenant, and it quickly becomes a lot to manage. Power BI workspace roles permissions alone trip up most new admins: there are four roles (Admin, Member, Contributor, Viewer), and assigning the wrong one either locks people out or gives them way more write access than they should have.
The other big source of confusion is content endorsement. Organizations with hundreds of semantic models floating around in various workspaces end up with users grabbing whatever dataset they find first, which may be outdated, untested, or just plain wrong. The endorsement system (promotion and certification) exists precisely to solve this, but most teams never configure it, so users keep building reports on bad data.
Gateway problems are their own category of pain. If your semantic model connects to on-premises data sources, SQL Server, Oracle, file shares, the on-premises data gateway sits between Power BI Service and your local network. Any misconfiguration there means scheduled refreshes silently fail, and users see stale numbers without any obvious error message explaining why.
I know this is frustrating, especially when it blocks your work and the error messages in Power BI Service are often cryptic one-liners that tell you nothing useful. That's exactly why this guide exists.
The Quick Fix, Try This First
Before you go deep into workspace roles and gateway logs, run through this checklist. About 60% of Power BI sharing problems I see come down to one of these five things, and you can check all of them in under five minutes.
1. Check that the recipient has a Power BI license. Go to the Microsoft 365 admin center → Users → Active users → find the person → Licenses and apps. They need either Power BI Pro or Premium Per User (PPU) to access content in a shared workspace. If your workspace is in a Premium capacity, viewers only need a free license, but they still need to have signed into Power BI at least once.
2. Verify semantic model permissions separately from report permissions. Open Power BI Service → navigate to the workspace → find the semantic model (not the report) → click the three-dot menu → Manage permissions. If the recipient's name isn't there, add them. This is the single most common cause of "I can see the report but the visuals won't load" errors.
3. Check workspace role assignment. In the workspace, click Settings → Access. Confirm the user is listed and has at least the Viewer role. Being added to a report share does not automatically add someone to the workspace. These are independent access grants.
4. Confirm the gateway is online (if applicable). Go to Settings (gear icon, top right) → Manage connections and gateways. If the gateway shows a yellow warning or "Offline" status, that's your problem, no report that touches on-premises data will refresh until the gateway is back.
5. Try sharing via an app instead of direct report sharing. If you're sharing with more than a handful of people, publish a Power BI app from the workspace instead of sharing individual reports. Apps give you a cleaner permission surface, dedicated navigation, and audience-level access control. Direct report sharing was designed for one-off ad-hoc use, not team-wide distribution.
Workspaces are the foundation. Every Power BI sharing and collaboration problem eventually traces back to workspace structure and role assignments, so get this right upfront.
Navigate to Power BI Service → Create → Workspace. Give it a clear, descriptive name, naming conventions matter more than most teams realize because workspace names surface in Excel, Teams, and SharePoint integrations. Once created, go to Workspace settings → Access.
Here's how the four Power BI workspace roles permissions break down in plain English:
- Admin, Full control. Can add/remove members, delete the workspace, publish apps, and modify all content. Only give this to workspace owners.
- Member, Can publish apps, share reports, and add contributors/viewers. Cannot delete the workspace or add other admins. Good for team leads.
- Contributor, Can create, edit, and delete content in the workspace. Cannot publish apps or share reports outside the workspace. Right for active report developers.
- Viewer, Read-only access to all content in the workspace. Cannot edit, publish, or share. Right for end-users who just consume reports.
A common mistake I see: assigning everyone the Contributor role "just to be safe." That gives every team member the ability to accidentally delete a report or overwrite a published semantic model. Be deliberate, assign the minimum role needed.
After saving role assignments, ask one of the newly-added viewers to try accessing the workspace from a private/incognito browser window. If they see the workspace and its reports, you're good. If not, wait five minutes, AAD permission propagation can lag slightly, and try again before digging further.
If your organization has more than a handful of workspaces, Power BI content endorsement isn't optional, it's essential for preventing people from building on bad data.
There are two endorsement tiers. Promotion is self-service: any content owner, or any workspace member with write permissions, can promote a semantic model, dataflow, report, or app. Promotion signals "this is good quality and ready to share", it's a community trust signal. Certification is admin-controlled: only a select reviewer group, defined by your Power BI administrator, can certify content. Certification signals "this meets official organizational quality standards."
To promote a semantic model: go to your workspace → find the semantic model → click the three-dot menu → Settings → scroll to Endorsement → select Promoted → Save.
Certification requires your Power BI admin to have enabled it first under Admin portal → Tenant settings → Endorsement and discovery → Certification. Once enabled, the admin defines which security groups can certify. If you need content certified and you're not in that group, follow your organization's internal process to request certification from a designated certifier.
Why does this matter for sharing? When a user in Excel searches for a Power BI semantic model to connect to, endorsed content is displayed with a badge and ranked higher in search results. In Power BI Service, the same applies to report discovery. I've watched teams cut the "which dataset should I use?" confusion by 80% just by consistently promoting their production-ready semantic models and certifying their master data sources.
Endorsed content is labeled with badges in lists, cards, report headers, and even inside Excel, so users don't have to guess which version of a dataset is the authoritative one.
Direct report sharing is fine for a quick one-off, but for any content you're distributing to more than five or six people on an ongoing basis, publishing a Power BI app is the right call. Apps give recipients a polished, stable view of your content without exposing the underlying workspace.
From your workspace, click Publish app in the top menu bar. You'll go through a setup wizard with three sections: Setup (name, description, logo, support site), Navigation (choose which reports/dashboards to include and how to organize them), and Permissions (who gets access).
In the Permissions section you can grant access to: specific people, security groups, distribution lists, or your entire organization. This is where app-based sharing shines over direct sharing, one audience definition controls access for everyone, and you update it in one place.
When you want to update the app after publishing (new reports, revised data, navigation changes), go back to the workspace and click Update app. Recipients automatically get the updated version, no re-sharing required.
One thing I tell every team I work with: if you're following the best practice of sharing data via apps, endorse the app itself, not just the underlying semantic model. Users discovering your content through Power BI search or the app marketplace should see the endorsement badge on the app so they know it's the authoritative, production-ready version.
After publishing, verify the app by opening it from Apps in the Power BI left nav. Check navigation flows correctly, confirm all reports load with live data, and test any row-level security rules with a test account before notifying your audience.
Getting Power BI reports surfaced inside the tools your team already lives in, Teams and SharePoint, dramatically increases report usage. Here's how to do both correctly.
Microsoft Teams integration: The Power BI app for Teams is the recommended path. In Teams, click Apps in the left sidebar → search for "Power BI" → Add. Once installed, you get a dedicated Power BI tab in Teams where you can browse workspaces and pin reports directly. For channel tabs: open any Teams channel → click the + tab button → select Power BI → pick the report you want to embed.
You can also share report links in Teams chat, when you paste a Power BI report URL, Teams generates a rich preview card. Recipients who have Power BI access click through to the live report. To get notifications about data changes in Teams, configure Power BI data alerts (on a dashboard tile) and route them to a Teams channel via Power Automate.
SharePoint Online embedding: Open the target SharePoint page in edit mode → Add a web part → choose Power BI from the web part picker → paste your report's embed URL. To get the embed URL: open the report in Power BI Service → File → Embed report → SharePoint Online → copy the URL shown.
Important: the Power BI SharePoint web part shows live, interactive reports, not screenshots. Users can filter, drill down, and interact with the data directly from the SharePoint page. But they still need a Power BI license and access to the underlying workspace or semantic model. The embed doesn't bypass Power BI permissions.
If you're also storing Power BI .pbix files in OneDrive or SharePoint document libraries, users can open and view those files in browser without switching to Power BI Service, useful for files shared as working drafts.
Sharing with people outside your Azure AD tenant, partners, clients, contractors in their own organization, used to mean exporting data or creating guest accounts. Power BI's in-place semantic model sharing feature changes that.
With in-place semantic model sharing, external users can connect to and analyze your semantic model from their own Power BI tenant. The data stays in your tenant. They get a live connection, not a copy. This is a meaningful security improvement over old approaches that involved data exports.
To share a semantic model with external users: go to the semantic model in your workspace → three-dot menu → Manage permissions → Add user → enter the external user's email address (their organizational account from their tenant) → choose the appropriate permissions level.
There are three semantic model permission levels to know: Read (can use it to build reports), Build (can create new reports and composite models on top of it), and Write (can modify the semantic model itself). For external partners, Read or Build is almost always the right choice.
Before external sharing works, your Power BI admin must enable it under Admin portal → Tenant settings → Export and sharing settings → Allow external guest users to edit and manage content in the organization. The specific in-place sharing capability also requires the external user's organization to be set up for B2B collaboration in Azure AD.
Once set up, the external user opens their own Power BI and navigates to Get data → Power BI semantic models, they'll see your shared semantic model listed there. They can then build reports against it in their own tenant while the data stays secured in yours.
# PowerShell: verify B2B guest user's current Power BI license state
# Run in your tenant's Azure AD context
Get-AzureADUser -ObjectId "guestuser@partnercompany.com" | Select-Object DisplayName, UserType, AssignedLicensesAdvanced Troubleshooting for Power BI Sharing Issues
When the standard fixes don't work, it's time to dig into the layers underneath. Here's where I go when a straightforward permission change doesn't resolve the problem.
Gateway failures and on-premises data refresh errors. If scheduled dataset refresh is failing silently, open Power BI Service → Settings → Manage connections and gateways → find your gateway → check status. A yellow triangle means connectivity issues. Click the gateway name → Status for detailed error output. Common culprits: the gateway Windows service stopped (check Services.msc on the gateway machine, look for "On-premises data gateway service"), the service account's password changed, or a firewall rule blocked outbound port 443 or 5671 to the Azure Service Bus endpoints.
On the gateway machine itself, gateway logs live at:
C:\Windows\ServiceProfiles\PBIEgwService\AppData\Local\Microsoft\On-premises data gateway\GatewayErrors*.log. Error code DM_GWPipeline_Gateway_MessageTargetInvalidOrUnreachable means the gateway can't reach Power BI Service endpoints, check your proxy settings and firewall rules. Error DM_GWPipeline_UnknownError combined with a data source credential error means the stored credentials on the gateway have expired and need to be re-entered.
Tenant-level settings blocking sharing. Power BI admins can restrict sharing at the tenant level. If users report that the "Share" button is grayed out or that embedding in SharePoint doesn't work despite correct permissions, check Admin portal → Tenant settings. Key settings to verify: "Allow users to share reports" (under Export and sharing), "Embed content in apps" (under Integration settings), and "Allow external guest users to access Power BI" (under Export and sharing). Any of these being disabled will cause silent failures for end users with no helpful error message.
Event-level diagnostics. Power BI has an activity log accessible via the Admin portal → Activity log, or via PowerShell using the Power BI Management cmdlets. For diagnosing who accessed what and when:
Login-PowerBI
Get-PowerBIActivityEvent -StartDateTime "2026-04-19T00:00:00" -EndDateTime "2026-04-20T23:59:59" | ConvertFrom-Json | Where-Object { $_.Activity -eq "ShareReport" }Row-Level Security (RLS) issues. If users can open a report but see no data (empty visuals, zero-count tables), RLS is the likely culprit. In Power BI Desktop, go to Modeling → Manage roles to review the DAX filter rules. In Power BI Service, you can test RLS by going to the semantic model → three-dot menu → Security → Test as role, then entering the email of the affected user. If the data is missing or wrong in the test view, that confirms an RLS misconfiguration.
Data lineage for impact analysis. Before changing a shared semantic model that multiple reports depend on, use the lineage view: in your workspace, click the lineage icon (branching paths icon near the top right). This shows every report and dashboard downstream of your semantic model. The semantic model impact analysis feature (three-dot menu → Impact analysis on a semantic model) shows which downstream items will be affected by changes, and lets you send a notification to the owners of those items before you make breaking changes.
PowerBIEntityNotFoundException or InvalidLicenseForOperation for users who do have valid licenses assigned. These categories require Microsoft-side investigation that no amount of client-side troubleshooting will fix.
Prevention & Best Practices for Power BI Sharing
Most of the Power BI sharing headaches I deal with are entirely preventable. They happen because teams set up workspaces in a hurry and never revisit the structure, or because someone promoted their personal development workspace to production without thinking through the permission model. Here's what good long-term hygiene looks like.
Separate development and production workspaces. Never let people build reports in the same workspace where you publish the production app. Create a [Name]-Dev workspace for active development, a [Name]-Prod workspace for the published app, and use deployment pipelines (Power BI Premium feature) or manual promotion to push tested content from dev to prod. This prevents draft reports from accidentally appearing in the audience-facing app.
Standardize on app-based distribution. Direct report sharing is a shortcut. Apps give you a stable URL, a controlled navigation structure, and a single audience configuration to update. When someone leaves the team, you update one place instead of hunting through dozens of individual report shares. Microsoft's own documentation positions app sharing as the best practice for broad audience distribution, follow that guidance.
Certify master semantic models and promote everything in production. Run a quarterly review of your production workspaces. Every semantic model and report that's actively used should be promoted at minimum. Your master data sources (the authoritative tables that multiple business units build on) should be certified. This prevents the creeping data trust problem where users don't know which version of a dataset is official.
Monitor the activity log. Set up a monthly review of Power BI activity logs to track share events, external access, and report export patterns. If someone is exporting sensitive data to Excel or PDF at unusual volumes, the activity log surfaces that before it becomes a data governance incident.
- Enable Power BI semantic model endorsement in your tenant settings today, it costs nothing and immediately improves data discoverability
- Add the Power BI app to your main Microsoft Teams workspace so analysts can find reports without switching apps
- Set a calendar reminder to review and clean up inactive workspaces every 90 days, orphaned workspaces are a governance risk
- Configure Power BI data alerts on critical KPI tiles and route them to Teams channels via Power Automate so the right people hear about threshold breaches instantly
Frequently Asked Questions
Why can my colleague see the report but all the charts are blank?
This almost always means they have access to the report but not to the underlying semantic model. Go to the workspace, find the semantic model (not the report), click the three-dot menu, choose "Manage permissions," and add their account with at least Read permission. Alternatively, if the semantic model is in a different workspace from the report, you'll need to grant them access to that separate workspace or to the semantic model directly. Power BI doesn't automatically cascade report-level access to the semantic model when they live in different places.
What's the difference between promoting and certifying a Power BI report?
Promotion is self-service, any content owner or workspace member with write permissions can promote their own report or semantic model to signal that it's ready for others to use. Certification is a higher-trust endorsement that means the content meets your organization's official quality standards. Only a select reviewer group defined by your Power BI administrator can grant certification, and the certification feature has to be explicitly enabled in the Admin portal first. Think of promotion as a "peer review passed" badge and certification as "official seal of approval from the data governance team."
How do I share a Power BI report with someone outside my company?
For external users in another Azure AD tenant, the modern approach is in-place semantic model sharing, they connect to your semantic model from their own Power BI tenant without data leaving yours. Your admin needs to enable external guest access in the Power BI tenant settings first. For one-off sharing with no Power BI account involved, you can also publish to web (which creates a public URL with no authentication, only do this for genuinely public, non-sensitive data) or export to PDF/PowerPoint. For ongoing partner collaboration, in-place semantic model sharing is the most secure and scalable path.
My scheduled data refresh keeps failing but there's no clear error, what do I check?
Start with the gateway. Go to Settings → Manage connections and gateways and check the gateway status. If it shows "Offline" or a warning, open the gateway machine, check Services.msc for the "On-premises data gateway service" status, and look at the gateway logs in C:\Windows\ServiceProfiles\PBIEgwService\AppData\Local\Microsoft\On-premises data gateway\. The GatewayErrors log files will usually tell you exactly what failed, credential expiry, firewall block, or service crash. After fixing the gateway, manually trigger a refresh from Power BI Service to confirm it works before waiting for the next scheduled run.
Can I embed a Power BI report in SharePoint without everyone needing a Power BI Pro license?
Yes, if your Power BI workspace is assigned to a Premium capacity (either Power BI Premium or Premium Per User). In that case, viewers only need a free Power BI license, not Pro, to view embedded content in SharePoint Online. If you're not on Premium, then every person who views the embedded report in SharePoint needs a Pro or PPU license. The SharePoint web part itself handles the rendering, but Power BI Service still enforces license checks on each viewer when the report data loads.
What workspace role should I give report consumers who only need to view dashboards?
Assign them the Viewer role. Viewer gives read-only access to all content in the workspace, they can open reports, interact with visuals, and use filters, but they can't edit content, publish changes, or share reports with others. For large audiences, though, the better practice is to publish a Power BI app from the workspace and grant audience access through the app rather than adding dozens of individuals to the workspace directly. App-based access is easier to manage, audit, and update when your audience changes.