Preflight checks for Microsoft Power BI
What each Microsoft Power BI crawler preflight check validates, the order they run in, and what a failure means.
Before running the Microsoft Power BI crawler, you can run preflight checks to perform the necessary technical validations. The checks correspond to the two permission layers. See The two permission layers for background.
The checks run in the order below. Every check except Admin capacities access blocks the run when it fails, and the checks after a failed one don't run, so fix the first failure and run preflight again.
Preflight validates access. Runs can still fail later at the publish stage: circuit breaker trips, lineage reference errors, and timeouts on very large estates. Those are covered in Connectivity errors.
The checks below also don't cover every permission a run uses: they confirm that some workspaces are visible, not that your role on each one is high enough, and they never call the Fabric API behind column and measure lineage. A green preflight can be followed by a successful run with that lineage missing. See No column or measure lineage.
Dashboard and report regex
Runs only when you set Include Dashboard and Reports Regex or Exclude Dashboard and Reports Regex. Validates that both expressions compile.
❌ The regex is invalid. Correct the expression on the crawler form.
Credentials scopes
Validates Layer 1: token issuance from Entra ID.
✅ Check successful
❌ Source returned error. Classic causes: AADSTS7000215 (Secret ID pasted instead of Value) or AADSTS7000222 (secret expired).
For example:
Credentials Scopes: Failed with response{"error":"invalid_client","error_description":"AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app '<client-id>'. ..."}#STATUS:401
Workspace permissions
Validates Layer 2: lists the workspaces the connection can see. With Enable Scanner API Access off this calls GET /v1.0/myorg/groups (Fabric public APIs); with it on, GET /v1.0/myorg/admin/groups (admin APIs).
✅ Check successful
❌ No Power BI workspaces were returned: the service principal has no workspace access. A 401 response indicates the "Fabric public APIs" tenant setting is disabled, or the read-only admin APIs setting when Enable Scanner API Access is on, or the service principal isn't in the required security group.
Workspace selection
Validates that at least one visible workspace is left after the Include Workspaces, Exclude Workspaces, and Exclude Workspaces Regex filters. If you set Exclude Workspaces Regex, also validates that the expression compiles.
❌ All Power BI workspaces were excluded by the configured filters. To fix, adjust the filters on the crawler form so at least one workspace is selected.
❌ Invalid workspace_exclude_regex: the Exclude Workspaces Regex value isn't a valid regular expression. Correct the expression on the crawler form.
Metadata scan
Validates Layer 2: the admin scanner APIs that do tenant-wide metadata extraction.
✅ Check successful
❌ Source returned error. Classic cause: PowerBINotAuthorizedException 401, which means the read-only admin APIs tenant setting is disabled or not scoped to your security group.
For example:
Failed with response{"error":{"code":"PowerBINotAuthorizedException","pbi.error":{"code":"PowerBINotAuthorizedException","parameters":{},"details":[],"exceptionCulprit":1}}}#STATUS:401
BIM file bucket
Runs only when Enable Power BI OLS Dataset Enrichment is on. Validates that the BIM file bucket lists, contains at least one .bim file, and that the file downloads and parses. See Enrich Power BI OLS datasets.
❌ The bucket, prefix, region, or role ARN is wrong, the role can't read the objects, or no BIM export exists under the prefix.
Admin capacities access
Advisory: a failure shows as a warning and doesn't block the run. Validates GET /v1.0/myorg/admin/capacities, which Atlan uses only for dataset refresh schedules (refreshables).
⚠️ Failed: the crawl runs, but refresh schedules are empty. Check the read-only admin APIs tenant setting.