Skip to content

Troubleshooting Guide

Common issues and resolutions for the Agent Access Governance Monitor.

Deployment Issues

Issue Cause Resolution
Tables not created deploy.py did not complete Re-run python scripts/deploy.py (full deployment is the default); check Dataverse System Administrator role
Environment variables missing Selective deployment skipped variables Run python scripts/deploy.py --vars-only to deploy variables only
Connection reference errors Connector unavailable, unbound, or not licensed Check connection binding and licensing. Microsoft Dataverse is a Premium connector, including in the lab model. For the scheduled flow, verify the owner's Power Automate Premium entitlement or an appropriately allocated Process license; see prerequisites.md.
deploy.py authentication failure Expired or invalid token Prefer python scripts/deploy.py --managed-identity on Azure-hosted automation, or --workload-identity --client-id <app-id> for CI/CD. For manual runs, re-run python scripts/deploy.py --interactive --client-id <app-id> to refresh the MSAL token cache. The deployment does not use az login; verify tenant and environment URL.
Schema version mismatch Partial upgrade from earlier version Re-run python scripts/deploy.py (full deployment is the default) to reconcile schema

Authentication Issues

Issue Cause Resolution
Modern OAuth token acquisition fails AAMClient.psm1 not imported, or app registration misconfigured Ensure scripts/private/AAMClient.psm1 is importable; verify the app registration allows public-client device-code flow (for -Interactive) or has a valid secret (for -ClientSecret)
Interactive auth popup not appearing Browser block or policy restriction Try a different browser; check Conditional Access policies
Service-principal auth fails with 401 Client secret expired or wrong app permissions Rotate the client secret; verify the app has the required Power Platform/Dataverse permissions. Certificate-thumbprint auth was removed (required the archived MSAL.PS module)
Insufficient privileges Missing Dataverse role Assign Dataverse User role (minimum) or System Administrator for schema deployment
Token expired during long export Access token TTL exceeded Re-run the export; token lifetime is typically 60 minutes

Validation Issues

Issue Cause Resolution
No environments returned PowerApps Admin module not connected Run Add-PowerAppsAccount before validation; verify Power Platform Admin role
Administration module cannot load under PowerShell 7.x Microsoft's module guidance requires Windows PowerShell 5.x; AAM also has PowerShell 7.x requirements Resolve the collector-host compatibility gate before scheduling scans. Changing only the Azure Automation runtime or downgrading the whole AAM chain to 5.1 is not a validated fix.
New limits appear ineffective Enforcement can take up to an hour, existing access is retained, or the agent does not require authentication Confirm authenticated-agent scope and wait for propagation. Review existing shares separately; only unsharing is allowed for an agent exceeding the new rules. See Microsoft's sharing semantics.
Uncapped does not match an expected product value AAM groups non-positive, missing, and non-integer viewer-cap input into its own comparison category Inspect raw settings and the per-agent viewer limit in Manage sharing. Do not treat AAM's handling of 0 or -1 as Microsoft-documented agent-cap behavior; see the verification record.
Zone classification errors Baseline record missing or zone not set Verify fsi_accessbaselines has an active record for the environment, or check naming convention fallback matches environment names
False positive violations Zone assignment incorrect Check zone classification in fsi_accessbaselines Dataverse table; re-capture baseline with correct zone via Invoke-AccessBaselineCapture.ps1
Grace period not applied fsi_AAM_GracePeriodHours set to 0 Set environment variable to desired hours (default: 48) in Dataverse
Sandbox environments included fsi_AAM_IncludeSandbox is true Set to false in Dataverse environment variables, or use -ExcludeSandbox flag

Drift Detection Issues

Issue Cause Resolution
Baseline not found No baseline captured yet Run Invoke-AccessBaselineCapture.ps1 to create initial baselines
"No previous validation" warning First run in environment Expected on first run; baseline is established after first successful validation
Validation history not persisting Missing Dataverse write permission Verify Create permission on fsi_accessvalidationhistory entity
Drift detected but setting is correct Stale baseline record Re-capture baseline with Invoke-AccessBaselineCapture.ps1 to update

Evidence Export Issues

Issue Cause Resolution
Empty export (0 records) No validation data in date range Adjust -FromDate and -ToDate; confirm validations have run
Export refuses to start on an older PowerShell version Export script requires PowerShell 7.4+ Run the export with PowerShell 7.4+; its Dataverse REST path is separate from the administration-module collector compatibility gate
Hash mismatch on verification File modified after export Re-export evidence; avoid opening JSON in editors that modify whitespace
Output directory permission denied Restricted file system path Use a writable directory; run as administrator if needed
Large export file (>100 MB) Extended date range with many violations Narrow -FromDate/-ToDate range, or filter by -Zone

Power Automate Flow Issues

Issue Cause Resolution
Flow not triggering Disabled or suspended flow Check flow status in Power Automate portal; re-enable if suspended
Adaptive card not sent Teams connection ref expired Re-authorize fsi_cr_teams_accessmonitor connection reference in Power Automate
Dataverse write failure (403) Managed identity lacks Create permission Assign Security role with Organization-level Create on fsi_accessvalidationhistory
Azure Automation job timeout Runbook exceeds default timeout Increase job timeout in Automation Account; check for environment query delays
Email alerts not received Office 365 connection expired or DL invalid Re-authorize fsi_cr_office365_accessmonitor; verify distribution list address
Connection auth expired Connections need periodic re-authorization Re-authorize all connection references; consider managed identity or certificate-based connections where supported