> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Power BI Access

> Common issues and solutions for Power BI connection problems in both frontend and backend access scenarios.

Power BI connections have separate frontend and backend functionality, even though everything is configured from the
backend connection. When troubleshooting issues, it's important to test each area separately since one might work
perfectly while the other fails completely.

***

## Backend User Permissions

After a Power BI connection is saved, the **Power BI** section may not appear in the backend navigation for
some users. This is a permissions issue: the connection is valid, but the backend user has not been granted
access to the Power BI plugin.

Saving a Power BI connection does not grant any Power BI permissions, not even to the user who saved it. Grant them
to each backend user who needs them:

1. Log in as a super-administrator.
2. Navigate to **Settings** > **Administrators**.
3. Open the affected user's record and click the **Permissions** tab.
4. Under the **Power BI** section, enable **Power BI administrator**.
5. Save the user record.

***

## User Menu Access Warnings

When viewing the **User Menu Access** tab in the backend, Power BI items may display an amber warning icon
(⚠) next to the menu entry.

This icon means Curator cannot preview a user's access to that item because the **Admin Registered App** is not
configured. Without an Admin connection, Curator has no way to query Power BI's Admin API to determine which
workspaces and reports a user can see.

**How to resolve:**
Complete the [Azure Admin Registered App Setup](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_admin_app_setup.md)
and enter the resulting credentials under
In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
navigate to the
**Settings**
\>
**Power BI Settings** page. on the **Admin** tab.

Once the Admin connection is saved, the warning icons will disappear and User Menu Access will correctly reflect
each user's Power BI permissions.

***

## Backend Troubleshooting

The backend integration with Power BI is straightforward - there's one reliable way to test it and only a few common
failure points.

### Test if Backend is Working

Follow these steps to verify your backend connection:

1. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Power BI**
   \>
   **Reports**

   page.

2. Click the **Clear Cache** button (top right) to ensure fresh data.

3. Click the **New Report** button to navigate to the "Create Report" page.

4. Use the dropdown menus to select a workspace and report

   * **Success:** If you can select both workspace and report, your backend is working! Skip to the
     [Frontend section](#frontend-troubleshooting)
   * **Problem:** If either dropdown is empty when it shouldn't be, continue to the troubleshooting steps below

![Power BI Backend Success](https://mintcdn.com/interworks/x0r9dMo3GyjABFAR/assets/images/creating_integrations/power_bi_connection/troubleshooting_power_bi_access_success.png?fit=max\&auto=format\&n=x0r9dMo3GyjABFAR\&q=85\&s=f913983afee72a2a025ec879dfadc93b)

### Debug Backend Issues

When the backend isn't working, you need to see what Power BI is actually telling Curator.

#### Enable Debug Mode

1. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Power BI Settings** page. Click on the **Advanced** tab.

2. **Enable debugging**
   Toggle on **Debug Mode for Power BI** and click save

   > [!WARNING]
   >
   > Debug mode increases logging and can fill up your server. Set a reasonable **Debug Mode Expiration**
   > (default: 24 hours).

3. **Repeat the steps to recreate the issue**
   Follow the steps in [Test if Backend is Working](#test-if-backend-is-working) again to recreate the issue while
   debug logging is enabled.

4. **Check the logs:**
   1. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
      navigate to the
      **Settings**
      \>
      **Logs**
      \>
      **Event Logs** page.

   2. **Find Power BI calls**
      Filter for `Power BI API Call` using the search box (top right)

   3. **Review responses**
      Click on entries to see Power BI's detailed responses

For more information about Curator's logging systems, see the [Logging Overview](https://docs.curator.interworks.com/site_administration/logging/logging_overview.md).

#### Common Solutions

**If you see error messages:**
The solution depends on the specific error. Contact Curator support if the fix isn't obvious.

Some errors may be prefixed with `POWER BI ERROR` or `ERROR during powerbi flow`, but others may have different text.

**If responses are blank:**
This means Curator can connect to Power BI, but the admin registered app (or non-admin registered app if not using admin)
lacks workspace access. Try these fixes:

##### 1. Grant workspace access

Follow the [Add Registered App to Power BI Workspace(s)](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/power_bi_workspace_access.md)
instructions

##### 2. Enable Fabric APIs

Follow the [Allow service principals to use Fabric APIs](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/power_bi_workspace_access.md)
instructions
*(Note: This change can take time to take effect in Power BI)*

##### 3. Check security groups

If Fabric APIs are restricted to specific security groups, ensure your registered apps are a member of one of those
groups.

### Expired or Rotated Client Secret

Azure client secrets have a finite lifetime. When you create a client secret in Azure, you choose an expiration
period (commonly 6, 12, or 24 months). Once the secret expires, Power BI will reject Curator's authentication
requests and all Power BI content will stop loading until a new secret value is generated in Azure and saved in
Curator's Power BI settings.

**Symptoms:**

* Power BI dashboards and reports that previously worked stop loading for all users at once.
* Backend test pages (such as **Power BI** > **Reports**) return authentication errors when fetching workspaces or reports.
* Event logs show errors mentioning `AADSTS7000222`, `Invalid client secret provided`, or `client secret has expired`.
* The **Admin** and **Non-Admin** tabs under In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
  navigate to the
  **Settings**
  \>
  **Power BI Settings** page. may
  still display the previously saved secret, but Azure no longer accepts it.

> [!NOTE]
>
> Curator authenticates to Power BI using a client secret only. Certificate-based authentication is not currently
> supported, so rotating the client secret is the only way to restore access once the existing secret has expired.

To rotate the client secret, follow the [Create a Client Secret](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_app_setup.md#create-a-client-secret)
steps in the Azure App Setup guide for the non-admin registered app (and the matching
[Create a Client Secret](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_admin_app_setup.md#create-a-client-secret)
steps in the Azure Admin App Setup guide if you have configured an Admin Registered App). Then enter the new secret
value in Curator as described in the [Curator Connection](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/curator_connection.md)
guide.

### Admin Permissions Appear Then Disappear

Sometimes the Admin Registered App works right after you save its credentials, then stops working within hours or
days. The pattern can repeat: access comes back, then disappears again. This pattern is different from an expired
secret, which fails once and stays failed until you rotate it.

**Symptoms:**

* The workspace and report dropdowns under **Power BI** > **Reports** > **New Report** populate at first, then come
  back empty. These dropdowns use the non-admin registered app, so this symptom points at that app.
* Users see Power BI items in navigation after they log in, then lose them later in the same day. Navigation uses
  the admin registered app, so this symptom points at that app.
* Event log entries for `Power BI API Call` alternate between full responses and blank or `401`/`403` responses.

> [!NOTE]
>
> Curator caches the result of each Power BI permission check for up to 60 minutes, so a change in Power BI or Azure
> can take up to an hour to show in the backend. Click the **Clear Cache** button in the top right of the backend to
> drop that cache. Frontend navigation works differently. When an Admin Registered App is configured, Curator downloads
> the list of reports each user can see at the moment that user logs in to Power BI, and stores that list in the
> Curator database. Clear Cache does not download the list again. A user must log in to Power BI again, for example by
> logging out of Curator and back in, before a change in Power BI or Azure shows in their navigation.

There are three common causes. Check them in this order.

#### 1. Tenant setting has not propagated or was turned off

The Admin Registered App depends on two Power BI tenant settings: **Service principals can call Fabric public APIs**
under *Developer settings*, and **Service principals can access read-only admin APIs** under *Admin API settings*.
Older tenants show the first setting as **Allow service principals to use Fabric APIs** or **Allow service
principals to use Power BI APIs**.
Both settings can take up to 15 minutes to propagate across your organization after you enable them. During that
window, some requests succeed and others fail. If another admin later turns a setting off, or removes the admin app
from the security group that the setting allows, access stops as soon as the cached permission checks expire.

1. Log in to the [Power BI admin portal](https://app.powerbi.com/admin-portal) and select **Tenant settings**.
2. Confirm that **Service principals can call Fabric public APIs** is enabled.
3. Confirm that **Service principals can access read-only admin APIs** is enabled.
4. If either setting is restricted to specific security groups, confirm that the admin registered app is still a
   member of one of those groups.
5. If you changed a setting, wait 15 minutes before you test again.

See [Power BI Workspace Access](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/power_bi_workspace_access.md) for the full
steps to enable each setting.

#### 2. Registered app was removed from a workspace

You manage workspace membership in Power BI, not in Curator. If another admin removes the registered app from a
workspace, or lowers its role, Curator loses access to that workspace once the cached permission checks expire.
Reports in other workspaces keep working, so the problem can look intermittent.

1. Log in to the [Power BI portal](https://app.powerbi.com) and click **Workspaces** in the left navigation.
2. Hover over a workspace that Curator uses, click the three dots, and choose **Workspace access**.
3. Confirm that both the non-admin and admin registered apps are listed with the **Admin** role.
4. Repeat for each workspace that Curator uses.

If an app is missing, follow the
[Add Registered Apps to Power BI Workspace(s)](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/power_bi_workspace_access.md#add-registered-apps-to-power-bi-workspaces)
steps to add it back.

#### 3. Client secret was created with a short expiry

Azure lets you choose a custom expiry date when you create a client secret. A secret created with an expiry of hours
or days works during setup and then fails as soon as the date passes. If an admin then creates another short-lived
secret, the cycle repeats.

1. Log in to the [Azure Portal](https://portal.azure.com) and open **App registrations**.
2. Open the admin registered app and click **Manage** > **Certificates & secrets**.
3. Check the **Expires** column for the secret that Curator uses.
4. If the secret has expired or expires soon, create a new one with an expiry of months rather than days.
5. Repeat steps 2 through 4 for the non-admin registered app.
6. Follow the [Expired or Rotated Client Secret](#expired-or-rotated-client-secret) steps to save the new value in
   Curator.

After you correct any of these causes, click the **Clear Cache** button in the top right of the backend and repeat
the steps in [Test if Backend is Working](#test-if-backend-is-working). Then ask an affected user to log out of
Curator and log back in, so that Curator downloads their Power BI report list again, and confirm that the Power BI
items return to their navigation.

***

## Frontend Troubleshooting

Once your backend connection works and you've published Power BI content to Curator's navigation, users should be able
to access it seamlessly.

### Expected User Flow

When everything is configured correctly (following [setup steps 1-4](https://docs.curator.interworks.com/creating_integrations/power_bi_connection/azure_app_setup.md)),
users should experience:

1. **Log in to Curator**
   Using the method configured in your [Authentication Settings](https://docs.curator.interworks.com/setup/authentication/overview.md).

2. **Authenticate with Power BI**
   *(This may happen automatically with SSO)*

3. **Access content**
   Curator displays all accessible content based on platform permissions:

   * Tableau content: controlled by Tableau
   * ThoughtSpot content: controlled by ThoughtSpot
   * Power BI content: controlled by Power BI

   > [!NOTE]
   >
   > Curator can add additional restrictions but cannot expand access beyond what the source platform allows.

### Content Loads But Displays Blank

If Power BI content appears in Curator's navigation and the page itself loads, but the report area renders as a
blank space with no visible error, the failure is happening inside the Power BI JavaScript SDK after Curator has
already handed off the embed.

Curator embeds Power BI content using *user-owns-data* embedding: the report is loaded with the signed-in user's own
Microsoft Entra ID (Azure AD) access token, and Power BI then decides what that individual user is allowed to see.
This means Curator's server-side work can succeed completely — the content is published, the user passes Curator's
own permission checks, and the embed URL is retrieved — while Power BI still declines to render the report for that
particular user.

Because this failure happens in the browser, it is not recorded in
In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
navigate to the
**Settings**
\>
**Logs**
\>
**Event Logs** page., and enabling **Debug Mode for
Power BI** will not capture it. The error is reported to the browser console instead:

1. Open the blank report page in Curator.
2. Open your browser's developer tools (**F12**) and select the **Console** tab.
3. Reload the page and look for an entry beginning with `onerror called`. Expand it to read the error message
   returned by Power BI.

This is most common the first time a newly onboarded group of users logs in, and it is usually caused by the user's
Power BI setup rather than by Curator:

* The user does not have a **Power BI Pro** or **Premium Per User (PPU)** license assigned.
* The user has not been granted access to the workspace, the report, or the report's underlying dataset.
* The report uses **Row-Level Security (RLS)** and the user has not been assigned to an RLS role.

To confirm where the problem lies, have the affected user open the same report directly in the Power BI service at
[app.powerbi.com](https://app.powerbi.com). If it does not render there either, the access must be corrected in
Power BI before Curator can display it.

Newly granted access can also take a short while to show up. Microsoft can take a few minutes to finish applying new
licenses, group memberships, or workspace roles, and when Power BI declines a report for a user, Curator briefly
remembers that result (30 seconds by default) before checking again. If a report is still blank right after access
was corrected, wait a moment and reload the page, or have the user fully sign out of Curator and sign back in —
completing the Microsoft sign-in prompt re-checks the user's access immediately. If your portal intentionally
restricts many reports and you would rather Curator re-check declined access less often, raise the **Failed
Permission Re-Check Interval** in Power BI Settings (up to one hour).

> [!NOTE]
>
> Expired access tokens are handled separately. Curator detects a `TokenExpired` error and requests a fresh token
> automatically, so an expired token is not a typical cause of a permanently blank report.
>
> For a user who has signed in to Power BI before, Curator also recovers a token that has expired and cannot be
> refreshed silently: it sends that user back through the Microsoft sign-in prompt on a later page load to establish a
> new token. An unexpected sign-in prompt appearing on a session that is already signed in to Curator is therefore
> normal recovery behavior, not a fault. This only applies to users who have completed the Microsoft sign-in at least
> once; a user who has never signed in to Power BI is prompted only through the normal Curator sign-in.

### Debug Frontend Issues

If users see other Curator content but Power BI content is missing from navigation, follow these steps:

#### Verify Power BI Authentication

1. **Enable frontend debug mode**
   Follow the steps to [enable frontend debug mode](https://docs.curator.interworks.com/site_administration/performance/troubleshooting_load_times.md).

   > [!TIP]
   >
   > Remember to disable this after troubleshooting.

2. **Add debug parameter**
   In your browser, add `?debug=1` to the URL
   * Example: `https://curator.yourcompany.com/` becomes `https://curator.yourcompany.com/?debug=1`
     \[!NOTE] If URL already has a `?` character in it, use `&debug=1` instead

3. **Check session data**
   * Look for the debug bar at the bottom of the screen
   * Click **Session** tab
   * Look for a **`powerbi`** > **`user`** entry to ensure it has an "accessToken" value.

4. **Interpret results**
   * **Missing entry:** The user has no Power BI access token. For a user who has never signed in to Power BI, the
     token is established through the Curator sign-in flow, so have the user log out of Curator and log back in,
     completing the Microsoft sign-in prompt. (Curator does not re-prompt such a user automatically on page load,
     to avoid trapping a user who cannot sign in to Power BI on a repeating redirect.)
   * **Valid entry:** Authentication succeeded but Power BI reports no accessible content → Continue to next section

#### Check Power BI API Responses

1. In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
   navigate to the
   **Settings**
   \>
   **Power BI Settings** page. Click on the **Advanced** tab.  Enable the
   **Debug Mode for Power BI** toggle and click save.

   > [!WARNING]
   >
   > This increases logging significantly. Set a reasonable **Debug Mode Expiration** (default: 24 hours).

2. **Clear cache:**
   Click **Clear Cache** button (top right) to force fresh API calls.

3. **Refresh frontend:**
   Go back to Curator's frontend and refresh the page.

4. **Check API logs:**
   If Power BI content still doesn't appear:
   * In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
     navigate to the
     **Settings**
     \>
     **Logs**
     \>
     **Event Logs** page.
   * Look for Power BI API calls
   * Click entries to view detailed responses

5. **Get support:**
   API responses can be complex. Send the details to Curator support for analysis. Meanwhile, verify the user has
   proper access to the Power BI workspace and content in question.

### Redirect URI Mismatch

If you see an error containing `AADSTS50011: The redirect URI specified in the request does not match the redirect URIs
configured for the application`, the Azure app registration is missing the correct redirect URI.

**To fix this:**

1. Go to the [Azure Portal](https://portal.azure.com) and find your app registration
2. Click **Manage** > **Authentication (Preview)** in the left navigation
3. Under the **Web** platform, add a redirect URI using your Curator portal's domain with the `/powerbi` suffix
   * Example: `https://curatorexample.com/powerbi`
4. Save the changes
5. Log out and log back in to Curator to verify the fix

### SSL Certificate Errors

If you encounter an error like this when testing Power BI connections:

```txt theme={null}
GuzzleHttp\Exception\RequestException: cURL error 60: SSL certificate problem: unable to get local issuer certificate
```

This occurs when PHP cannot verify SSL certificates for HTTPS connections to Power BI API and Azure AD OAuth endpoints.
This is most common on Windows servers where the CA certificate bundle is not properly configured.

Curator provides three ways to configure SSL certificate verification through the `POWER_BI_SSL_VERIFY` environment variable:

* **Default**: Standard SSL verification (works on properly configured servers)
* **CA Bundle**: Download and configure a certificate bundle for secure verification
* **Off (*not recommended*)**: Turn off verification entirely (development only)

#### Enabling SSL CA Bundle

This is the most secure solution. You'll download a trusted certificate bundle and configure Curator to use it.

1. **Download the CA bundle:**
   Visit [https://curl.se/ca/cacert.pem](https://curl.se/ca/cacert.pem) and save the file to your server in a location
   readable by your web server.

   > [!TIP]
   >
   > On Windows, a good location is `C:\InterWorks\cacert.pem` or in your Curator installation directory.
   > On Linux, consider `/etc/ssl/certs/cacert.pem` or `/var/www/curator/cacert.pem`

2. **Configure the environment variable:**
   Add or update the following line in your `.env` file with the full path to your downloaded CA bundle:

   ```env theme={null}
   POWER_BI_SSL_VERIFY='C:\InterWorks\cacert.pem'
   ```

   Edit the `.env` file of the Curator instance that connects to Power BI. It sits in that instance's installation root,
   in the same folder as the `artisan` file. On a Central Dispatch install, each managed instance has its own
   installation folder under the worker's install path (for example `C:\InterWorks\Curator\htdocs\<instance folder>`).
   Put the setting in that managed instance's `.env`, not in the Central Dispatch controller's `.env`.

   > [!NOTE]
   >
   > On Windows, wrap the path in single quotes, as shown above, or use forward slashes
   > (`POWER_BI_SSL_VERIFY=C:/InterWorks/cacert.pem`). Inside double quotes a backslash starts an escape sequence, so
   > `"C:\InterWorks\cacert.pem"` makes the whole `.env` file invalid and the site stops loading. If you need double
   > quotes, double each backslash: `"C:\\InterWorks\\cacert.pem"`.

   > [!WARNING]
   >
   > The file must exist at that exact path and be readable by the web server user. If it isn't, every Power BI request
   > fails with an error such as `Power BI SSL verification: CA bundle file not found at configured path` or
   > `CA bundle file exists but is not readable`. Check the web server's error log and
   > `storage/logs/system-YYYY-MM-DD.log` in the instance's installation folder for the full message.

3. **Apply the change:**
   If the configuration has been cached, run `php artisan config:clear` from the instance's installation folder,
   because cached configuration ignores the `.env` file. Then restart the web server (Apache or IIS) so every PHP
   process picks up the new value.

4. **Test the connection:**
   Follow the steps in [Test if Backend is Working](#test-if-backend-is-working) to verify the error is resolved.

#### Disable SSL Verification

You can disable SSL verification entirely, but this creates serious security risks.

> [!WARNING]
>
> Disabling SSL verification exposes your application to man-in-the-middle attacks where an attacker could intercept
> credentials and data. **NEVER use this in production environments.** This should only be used temporarily in isolated
> development environments.

1. **Set the environment variable:**
   Add or update the following line in your `.env` file:

   ```env theme={null}
   POWER_BI_SSL_VERIFY=false
   ```

   Use the `.env` file of the Curator instance that connects to Power BI, as described in
   [Enabling SSL CA Bundle](#enabling-ssl-ca-bundle), then apply the change the same way.

2. **Test the connection:**
   Follow the steps in [Test if Backend is Working](#test-if-backend-is-working) to verify the error is resolved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.