Troubleshooting¶
Find the message or symptom you see, then apply the fix; backup problems come first, restore problems second.
MetaMiner translates Power BI errors into plain sentences. The full Microsoft response is always one click away: Details... on the wizard steps, the details expander on a Run now error, or the reason pane in Run history.
Access and permissions¶
Access step shows needs grant, or the job is Invalid with No access to workspace '...'
Cause: The backup service principal is not a member of the workspace.
Fix: Edit the job, go to Access, click Grant (or Grant all), then finish the wizard to save the job again. See Prerequisites and Access.
Grant fails with Delegated grant - ... and Admin grant - ...
Cause: Your account cannot add people to the workspace, and you are not a Fabric administrator.
Fix: Ask a workspace Admin to click Grant, or add the service principal to the workspace as Contributor in Power BI, then return to the Access step.
this workspace doesn't allow access changes through the API
Cause: Some workspaces, for example Microsoft-managed ones, refuse access changes through the API.
Fix: Grant the service principal access in the Power BI portal, or remove the workspace from the job.
The service principal could not list its workspaces (HTTP ...) or The service principal check failed
Cause: The environment's service principal cannot sign in or call Power BI: wrong secret, expired secret, or tenant settings not enabled for it.
Fix: Validate the environment in MMA and fix what it reports. Check Service principals can use Fabric APIs in the Fabric admin portal. See Validate the Connection and Tenant Settings.
Couldn't reach the Power BI service - check your network/VPN and retry.
Cause: MMS could not reach the Microsoft endpoints.
Fix: Check the server's network, proxy and firewall rules, then retry. See Network and Microsoft Endpoints.
Restore: Could not check the target ... Sign in again to grant the missing permission, then Re-check.
Cause: Your delegated sign-in lacks a permission this restore needs, for example Dataflow.ReadWrite.All for a Gen1 dataflow or Content.Create for a paginated report.
Fix: Make sure the permission is on the app registration with consent, sign in again when prompted, then click Re-check. See the permission table in Prerequisites and Access.
Review lists items under Not permitted with your access
Cause: Your own account cannot write to that workspace or perform that action.
Fix: Choose another target workspace, or have a workspace Admin give you a role that can write content.
Item type not supported¶
this item can't be exported - Power BI has no definition export for it, or not found or not exportable
Cause: Power BI offers no definition export for this item. Its own system items, such as usage metrics reports and their models, are the common case.
Fix: Select the workspace as partial and leave the item out, or exclude it from the job. Run Test on the Review step to find every such item before saving.
this item type can't be captured by the service principal
Cause: Power BI does not let a service principal export this item type.
Fix: Remove the item from the job.
this workspace type can't be backed up
Cause: The API refuses this kind of workspace, for example a Microsoft-managed one, whoever asks.
Fix: Remove the workspace from the job. Granting access does not change this.
A semantic model fails with a Direct Lake message
Cause: The model reads its data from OneLake (Direct Lake) and its workspace is not on a Fabric capacity that can load it, or the capacity is paused.
Fix: Put the workspace on a Fabric capacity that supports Direct Lake (an F SKU or a Trial capacity), or resume the capacity. Excluding the model stops it being backed up at all.
Some objects are not in the restore wizard, or Review says objects cannot be restored
Cause: Record-only types (dashboards, apps, lakehouses, warehouses and others) are listed in the archive but never captured, so there is nothing to restore. See What Is Backed Up.
Fix: None in MetaMiner. Recreate those items in Power BI. Show not captured in the wizard or in View contents lists them with the reason.
Fabric items fail when restored into a workspace
Cause: Notebooks, lakehouses, warehouses and other Fabric items need a workspace on a Fabric capacity.
Fix: Restore into a workspace on a Fabric capacity, or assign one to the target workspace and restore those items again.
Long-running operations¶
Run now takes a very long time
Cause: A backup captures every object; large workspaces, .pbix data and per-object capture take longer. Power BI exports are long-running operations that MetaMiner waits on.
Fix: Prefer Auto over Per-object. Schedule large jobs outside working hours. Leave .pbix data off unless you need it.
rate-limited by Power BI - try again shortly, or Power BI service error - try again shortly
Cause: Power BI throttled the requests or had a temporary fault. MetaMiner already retries throttled calls before giving up.
Fix: Run the job again later, or move its schedule to a quieter time.
The run fails with Bulk method
Cause: Bulk has no fallback: paginated reports, Gen1 dataflows, workspaces without capacity and items bulk refuses fail the run.
Fix: Edit the job and set Method to Auto.
A run shows Failed after the server was restarted
Cause: Runs in progress when MMS stopped are marked Failed when it starts again.
Fix: Run the job again with Run now, or wait for the next scheduled run.
A scheduled job never runs
Cause: The job is Manual, Invalid, past its schedule's end condition, or the previous run is still in progress. If the first Power BI environment was enabled after MMS started, the scheduler is not running.
Fix: Check Schedule and Validity in the jobs grid and the end condition in the schedule. Restart MMS if needed. See Start and Stop the Server.
Restore: Lost contact with the server. The restore may still be running there.
Cause: The MMC could not reach MMS for about two minutes.
Fix: Check the connection to MMS. The restore continues on the server; check the target workspaces in Power BI.
Name conflicts¶
What happens shows Already there - choose
Cause: Something with the same name and type is already in the target workspace, and the row did not come from there.
Fix: Choose Overwrite (replace it in place, keeping its id), Keep both (restore beside it under a new name) or Skip.
Name taken, or Another row in this restore already uses the name
Cause: The new name typed for Keep both is already used in the target, or by another row in this restore.
Fix: Type a different name.
... would land on the same name in the same workspace as another archived object
Cause: Two archived objects of the same type and name are going to the same workspace. No conflict choice can decide which survives.
Fix: Send one to another workspace, or give one a new name.
A Gen1 dataflow of this name is already there
Cause: Power BI cannot overwrite a Dataflow Gen1.
Fix: Choose Keep both with a new name, or delete the existing dataflow in Power BI and restore again.
A workspace called ... already exists
Cause: Workspace names are unique per tenant.
Fix: Give the new workspace another name, or pick the existing workspace as the target.
The restore did not start: the targets had changed since the plan was made.
Cause: Something in the target workspaces changed between Review and the run. Nothing was written.
Fix: Go back to Place, check the rows listed, then run again.
After a restore¶
Restored models or dataflows fail to refresh
Cause: Credentials and gateway bindings are never stored in an archive.
Fix: Re-enter the data source credentials and gateway binding in Power BI, then refresh.
Workspace access shows access grant(s) refused
Cause: Power BI refused some of the archived access entries, for example a user or group that no longer exists. Entries already present are reported as already had access, not as failures.
Fix: Read the run line with Details, then add the missing access in Power BI.
Notifications¶
No email arrives for a failed run
Cause: The job owner has no email on their MetaMiner user and no default recipient is set, or email is not configured in MMA.
Fix: Add an email to the owner's MetaMiner user or set the default recipient in Email, or add addresses under Notify on the job's Schedule step.