Validation Errors¶
Every check the MetaMiner Administrator (MMA) runs when you validate a Power BI environment, what a failure means, and how to fix it.
How validation works¶
When you click Test Connection in the Add Power BI Environment or edit dialog, the MMA signs in as your app registration (service principal) and calls each Microsoft API that collection needs. It shows "Validating Power BI environment name (...)..." and then a results dialog.
- Each step shows a green check, or a red name with the error text and, in grey italics, the advice.
- The last line reads "Steps passed: n, Steps failed: m".
- The dialog title is Validation Successful when every step passed, otherwise Authentication Failed.
- On failure you can Save Anyway. The environment is then saved disabled; fix the cause, validate again and enable it.
Collection needs the read-only admin API step
MetaMiner starts collecting for an environment only after the step Service principals can access read-only admin APIs has passed. Other failed steps leave parts of the data empty.
Image of the Power BI validation results dialog with several green steps, one failed step 'Fabric API' with its red error text and grey advice, and the line 'Steps passed: 9, Steps failed: 1'
../../images/help/pbi-validation-results.png
The validation runs in the MMA on the server. Details of each failure, including the HTTP status Microsoft returned, are in server\logs\admin.log.
Steps in order¶
| Step name in the dialog | What it checks |
|---|---|
| PBI API Token creation | The tenant ID, client ID and client secret can obtain a Power BI token |
| Service principals can access read-only admin APIs | The admin capacities API answers (read-only admin API access) |
| Fabric API | The Fabric gateways API answers (service principals may use Fabric APIs) |
| PBI API/Workspaces | The admin workspaces API answers |
| PBI Workspaces Scan API | A small workspace scan starts, completes and returns a result |
| Fabric Capacity Metrics Data dataset ID | Each configured Capacity Metrics semantic model answers a query and returns capacities |
| Graph API Token creation | The same credentials can obtain a Microsoft Graph token |
| Directory.Read.All, or each of User.Read.All, Group.Read.All, GroupMember.Read.All, Application.Read.All, LicenseAssignment.Read.All | The Graph token carries the application permissions MetaMiner needs |
Failures and fixes¶
PBI API Token creation: "Failed to create PBI API Token: ..."
Advice shown. "Make sure this Service Principal is created and enabled in Entra"
Cause. Microsoft Entra ID refused to issue a token. The text after the colon is Microsoft's reason. Common causes: wrong Tenant ID or Client ID, a wrong or expired Client Secret (copy the secret value, not the secret ID), the app registration disabled or deleted, the wrong Endpoint Set for your cloud, or a proxy blocking the sign-in endpoint.
Fix. Check the three values against the app registration's Overview and Certificates & secrets pages; create a new secret if it expired. Pick the Endpoint Set of your cloud. Check that the server can reach the sign-in endpoint (see Ports and Endpoints). The remaining steps do not run until this one passes.
See Register the Application, Client Secret and Sovereign Clouds.
Service principals can access read-only admin APIs: "Unable to check Power BI Service Administrator rights"
Advice shown. "Make sure you have added the Security Group to which the Service Principal belongs in PowerBI Admin portal settings "Allow service principals read-only access""
Cause. The service principal may not call the Power BI admin APIs. The tenant setting that allows service principals to use read-only admin APIs is off, or it is limited to security groups that do not include the service principal.
Fix. Add the service principal to a security group, and allow that group in the admin API tenant setting in the Fabric admin portal. Tenant setting changes can take some minutes to apply; validate again afterwards.
Fabric API: "Unable to access the Fabric API"
Advice shown. "Enable the tenant setting "Service principals can use Fabric APIs" for this service principal's security group"
Cause. This is a different tenant setting from the read-only admin APIs. Without it MetaMiner cannot collect gateways, connections, Fabric items and item definitions, and backup cannot run.
Fix. Enable the setting for the service principal's security group in the Fabric admin portal, wait for it to apply and validate again.
PBI API/Workspaces: "Failed to validate PowerBI Workspaces API"
Advice shown. "Check access to Workspaces API"
Cause. The admin workspaces list was refused. Usually the same cause as the read-only admin API step.
Fix. Fix the read-only admin API access first, then validate again.
PBI Workspaces Scan API: "Failed to validate workspace getInfo API" / "scan status API" / "scan API" / "getResult API"
Advice shown. "Check access to Workspaces API" or "Check access to PBI Workspaces Scan API"
Cause. The workspace scanner (the metadata scanning admin API) refused the request, did not finish, or did not return a result. "scan status API" also appears when the workspaces step failed, because there was no workspace to scan.
Fix. Fix the earlier steps first. Check that the admin API tenant settings for detailed metadata are on (see Tenant Settings). If Microsoft is throttling the tenant, wait and validate again.
Fabric Capacity Metrics Data: "Validation skipped" / "No FCM configured"
Cause. No Capacity Metrics semantic model is entered, and Ignore FCM at this time is not ticked. This step then counts as failed.
Fix. Either add the semantic model ID (see Capacity Metrics Datasets), or tick Ignore FCM at this time if you do not use capacity metrics yet.
Fabric Capacity Metrics Data dataset ID: "Validation failed"
Advice shown. "Make sure your service principal or the security group they are in is a Contributor or Admin on the workspace that hosts the Fabric Capacity Metrics App semantic model"
Cause. The query on the semantic model was refused, or the ID is not a Capacity Metrics semantic model.
Fix. Give the service principal (or its group) the Contributor or Admin role on the Capacity Metrics app workspace, and check the semantic model ID. See Capacity Metrics App.
Fabric Capacity Metrics Data dataset ID: "Unsupported Capacities column layout"
Cause. The semantic model answered, but its Capacities table has columns this MetaMiner version does not recognise. Collection would skip the per-capacity data for this model.
Fix. Check the version of the Fabric Capacity Metrics app. Tick Ignore FCM at this time until a supported version is installed, and send the column names from the message to Infolytik Support.
Fabric Capacity Metrics Data dataset ID: "No capacities returned"
Advice shown. "The Capacities table of the semantic model is empty. Make sure the Fabric Capacity Metrics app has been refreshed and the service principal can see at least one capacity."
Fix. Refresh the Capacity Metrics app in Power BI, then validate again.
Graph API Token creation: "Failed to create Graph API token"
Advice shown. "Make sure your credential for obtaining a GRAPH token are correct"
Cause. The credentials work for Power BI but Entra ID did not issue a Microsoft Graph token, for example because of the wrong Endpoint Set. The Graph permission checks do not run.
Fix. Check the Endpoint Set and the app registration; validate again.
Role "User.Read.All" (or Group.Read.All, GroupMember.Read.All, Application.Read.All, LicenseAssignment.Read.All) is required
Advice shown. "Make sure the Service Principal has "role" or "Directory.Read.All" role"
Cause. The app registration lacks a Microsoft Graph application permission, or admin consent was not granted. Without it the Entra users, groups and licence data stay empty (Licensing dashboard, Entra tab).
Fix. Add the missing Application permission on Microsoft Graph, or Directory.Read.All which covers all of them, and click Grant admin consent. See API Permissions.
"PBI environment validation failed" with a message
Advice shown. "Check MetaMiner Admin logs for details"
Cause. An unexpected error stopped the validation part-way.
Fix. Read the error in server\logs\admin.log and send it to support if it is not a network or credential problem.
Many API steps fail at once?
If token creation passes but most API steps fail together, check the network path first: a proxy or TLS inspection between the server and the Microsoft endpoints can make API calls fail even when permissions are correct. admin.log shows the HTTP status of each call.
Other messages in the environment dialog¶
| Message | Cause | Fix |
|---|---|---|
| Can't Add Power BI Environment: "Power BI environment with this host name already exist. ..." | The tenant ID is already configured in another Power BI environment. Each tenant is configured once. | Select the existing environment and click Edit |
| "Validating Power BI system connectivity failed!" | The validation could not run at all | Read the details in the dialog and admin.log |
| Server Is Not Found or Down: "Host ... is not found or down." / Authentication Failed: "Authentication failed for host ..." with "Please make sure that your connection parameters are correct." | The validation failed before the step checks could run | Check network access and credentials, then retry |
| Invalid UUID: "Invalid UUID format: ..." | The Capacity Metrics semantic model ID is not a UUID | Paste the ID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Duplicate UUID: "This UUID is already in the list." | The same semantic model was added twice | Remove the duplicate |
| "Failed to load FCM capacities" | Load Capacities could not query the Capacity Metrics model | Fix the FCM access as above |
| "Power BI environments require PostgreSQL 16 or newer for MetaMiner MMDB. ..." | The MetaMiner Database runs an older PostgreSQL; the environment cannot be enabled | Contact support to upgrade the MMDB. See Choose the MetaMiner Database |
| "Please note that MetaMiner Security is enabled and there is no user which has been assigned a security role other than 'No Access' for this environment. ..." | User-based security is on and nobody may see the new environment | Assign a role. See Users and Roles |
TODO: confirm the validation message when the service principal lacks Fabric administrator rights
The validator checks tenant settings and Graph roles; confirm whether any step reports a missing Fabric administrator role or workspace membership for item definitions.