Validate the Connection¶
What MMA checks when it validates a Power BI environment, in which order, and how to fix each failure.
How it works¶
MMA validates a Power BI environment when you click Test Connection or Apply in the environment dialog, and for every environment each time MMA starts. The checks run in MMA on the MetaMiner Server machine, as the service principal, against the endpoint set you chose. They read data only.
The result is a list of steps, each with a green check or a red error, an error text and a hint, followed by "Steps passed: N, Steps failed: M". The dialog title is Validation Successful when every step passes, otherwise Authentication Failed.
Image of the Authentication Failed results dialog with the Fabric API step failed, its error text and hint, and the Save Anyway and Close buttons
../../images/admin/pbi-validation-failed.png
A step counts as passed only when it has no error text. One failed step fails the whole validation.
Validation steps¶
| Order | Step name in the dialog | What MMA calls | Passes when |
|---|---|---|---|
| 1 | PBI API Token creation | Microsoft Entra ID token for the Power BI API | A token is issued. If this fails, validation stops here. |
| 2 | Service principals can access read-only admin APIs | Power BI admin API, list of capacities | The call succeeds. Also records the version that lets MMS collect this environment. |
| 3 | Fabric API | Fabric API, list of gateways | The call succeeds |
| 4 | PBI API/Workspaces | Power BI admin API, first workspaces of the tenant | The call succeeds |
| 5 | PBI Workspaces Scan API | Admin workspace scan of one workspace: start, poll status for up to 1 minute, read the result | The scan completes and its result can be read |
| 6 | Fabric Capacity Metrics Data <dataset ID> |
A DAX query on each listed capacity metrics dataset | The query returns at least one capacity in a supported layout. One step per dataset. |
| 7 | Graph API Token creation | Microsoft Entra ID token for Microsoft Graph | A token is issued. If this fails, the Graph role steps are skipped. |
| 8 | Graph roles | The roles in the Graph token | Directory.Read.All is granted, or each of User.Read.All, Group.Read.All, GroupMember.Read.All, Application.Read.All and LicenseAssignment.Read.All is granted. One step per role. |
Step 6 is skipped silently when Ignore FCM at this time is checked. With no dataset listed and the check box clear, it shows "Validation skipped" with "No FCM configured" and counts as failed.
Failure messages and fixes¶
| Step | Error text | Fix |
|---|---|---|
| PBI API Token creation | Failed to create PBI API Token: <Microsoft message> |
Check Tenant ID, Client ID, Client Secret and Endpoint Set. Make sure the app registration exists, is enabled and the secret has not expired. See Client Secret. |
| Service principals can access read-only admin APIs | Unable to check Power BI Service Administrator rights | Add the service principal's security group to the tenant setting that allows service principals read-only access to admin APIs. See Tenant Settings and Security Group for the App. |
| Fabric API | Unable to access the Fabric API | Enable the tenant setting "Service principals can use Fabric APIs" for the service principal's security group. |
| PBI API/Workspaces | Failed to validate PowerBI Workspaces API | Check the read-only admin API setting as for step 2; the Microsoft response is in admin.log. |
| PBI Workspaces Scan API | Failed to validate workspace getInfo API, scan status API, scan API or getResult API | Check the service principal's access to the admin workspace scan APIs (the same read-only admin API setting as step 2), then retry; the Microsoft response is in admin.log. The step also fails when the tenant has no workspace at all. |
| Fabric Capacity Metrics Data | Validation failed | Make the service principal, or its security group, a Contributor or Admin of the workspace that hosts the Fabric Capacity Metrics app semantic model. Check the dataset ID. |
| Fabric Capacity Metrics Data | Unsupported Capacities column layout | The installed Capacity Metrics app version uses a layout this MetaMiner version does not read. Check the app version, or check Ignore FCM at this time until MetaMiner supports it. |
| Fabric Capacity Metrics Data | No capacities returned | Refresh the Capacity Metrics app semantic model in Power BI and make sure it reports at least one capacity. |
| Fabric Capacity Metrics Data | Validation skipped | No dataset is listed. Add one or check Ignore FCM at this time. |
| Graph API Token creation | Failed to create Graph API token | Same checks as the Power BI token step |
| Graph role steps | Role "<role>" is required |
Grant the application permission Directory.Read.All, or the listed role, on Microsoft Graph and grant admin consent. See API Permissions. |
| PBI environment validation failed | An unexpected error | Check admin.log for details (File > Open MetaMiner Administrator Log). |
Tenant setting changes in the Fabric admin portal can take some time to take effect. Wait, then click Test Connection again.
What happens with the result¶
| Where you validated | All steps passed | A step failed |
|---|---|---|
| Test Connection | Results dialog only; nothing is saved | Results dialog only; nothing is saved |
| Apply in Add Power BI Environment | Environment saved, enabled, status Validated | Not saved; the dialog stays open. Save Anyway saves it disabled with status Failed. |
| Apply in Edit Power BI Environment | Changes saved; status Validated; the Enabled state stays as it was | Changes saved, status Failed, environment disabled |
| MMA startup | Status Validated | Status Failed; failed steps are kept as the status details |
An environment with status Failed cannot be enabled. MMA shows "failed validation and cannot be enabled" with the reason. Fix the cause, edit the environment and click Apply.
Duplicate tenant
Before validating, MMA checks that no other environment uses the same tenant ID. If one does, it shows Can't Add Power BI Environment with the message "Power BI environment with this host name already exist." Edit the existing environment instead.