Why did my TrueConfig scan timeout?

Scan timeouts usually occur with large tenants (10,000+ users), Microsoft Graph slowdowns, complex role structures, or high app registration counts. Try waiting 5-10 minutes and retrying, check Microsoft 365 Service Health, reduce scan frequency, or contact support for enterprise tenants.

How do I fix Graph API throttling (429 errors)?

TrueConfig automatically handles throttling with exponential backoff retries. If throttling persists, wait a few minutes before retrying, stagger multi-tenant scans at least 30 minutes apart, identify other API consumers, and consider reducing scan frequency.

Why is my scan showing partial data?

Partial scan data can result from missing permissions, API endpoint failures, license requirements (some data requires Entra ID P1/P2), or pagination issues. Verify all 8 required permissions are granted, check scan logs, and ensure proper Entra ID licensing.

How do I fix token refresh failures?

Token refresh failures occur when client secrets expire, admin consent is revoked, the app registration is deleted, or Conditional Access blocks service principal authentication. Check client secret expiration, verify admin consent, and reconnect the tenant if needed.

What are typical scan times by tenant size?

Expected scan durations: less than 100 users takes 1-2 minutes, 100-1000 users takes 2-5 minutes, 1000-10000 users takes 5-15 minutes, and more than 10000 users takes 15-30 minutes.

Documentation/Troubleshoot/Scan Failures

Scan Failures

Diagnose and resolve issues when TrueConfig scans fail or produce incomplete results.

Timeout Errors

Problem

Scan fails with error: "Scan timed out" or "Operation exceeded maximum duration"

Causes

Large tenant size: Tenants with 10,000+ users may exceed the 30-minute scan timeout
Microsoft Graph slowdowns: Temporary API latency from Microsoft's side
Complex role structures: Many PIM-eligible roles or nested groups increase processing time
High app registration count: Tenants with 500+ app registrations take longer to scan

Resolution

1. Retry the Scan

Many timeout errors are transient. Wait 5-10 minutes and trigger a manual scan from the dashboard. Temporary Graph API slowdowns often resolve themselves.

2. Check Microsoft 365 Service Health

Visit Microsoft 365 Service Health to check for known outages affecting Microsoft Graph or Entra ID.

3. Reduce Scan Frequency

For very large tenants, switch from hourly to daily scans. This reduces API load and allows more time for each scan to complete.

4. Contact Support

If timeouts persist across multiple retry attempts, contact support@trueconfig.io with your tenant ID. We can investigate chunked scanning options for enterprise tenants.

Expected Scan Times

Typical scan durations by tenant size:

<100 users: 1-2 minutes
100-1,000 users: 2-5 minutes
1,000-10,000 users: 5-15 minutes
>10,000 users: 15-30 minutes

Graph API Throttling (429 Errors)

Problem

Scan logs show HTTP 429 Too Many Requests errors or "Rate limit exceeded" messages.

Causes

Concurrent API usage: Other applications or scripts hitting Microsoft Graph simultaneously
Multiple TrueConfig tenants: Scanning multiple tenants at the same time
Manual + scheduled scan overlap: Triggering a manual scan during a scheduled scan window
Microsoft-side throttling: Tenant-wide Graph API quota limits

How TrueConfig Handles Throttling

Automatic retry: TrueConfig automatically retries throttled requests with exponential backoff
Retry-After header: When Microsoft returns a Retry-After header, TrueConfig waits the specified duration
Max retries: Up to 5 retry attempts per request before failing

Resolution

1. Wait and Retry

Rate limits typically reset within 1-5 minutes. Wait a few minutes before triggering another scan.

2. Stagger Multi-Tenant Scans

If managing multiple tenants, configure scan schedules at least 30 minutes apart to avoid concurrent API usage.

3. Identify Other API Consumers

Check if other tools or scripts are consuming Graph API quota. PowerShell scripts, third-party security tools, and backup solutions can contribute to throttling.

4. Reduce Scan Frequency

Switch from hourly to daily scans if throttling occurs frequently. Daily scans still provide strong security coverage.

Graph API Limits

Microsoft Graph enforces per-tenant and per-app rate limits. TrueConfig is designed to stay within limits, but heavy concurrent usage from multiple sources can trigger throttling.

Partial Scan Data

Problem

Scan completes but some controls show "Data unavailable" or user counts seem lower than expected.

Causes

Missing permissions: Required Graph API permissions not granted or admin consent revoked
API endpoint failures: Individual API calls failed during scan but didn't cause a full failure
License requirements: Some data (like sign-in activity) requires specific Entra ID licenses
Pagination issues: Large data sets may have been truncated due to API limits

Resolution

1. Verify All Permissions

Ensure all 8 required permissions are granted with admin consent:

User.Read.All
Policy.Read.All
Application.Read.All
RoleManagement.Read.Directory
Group.Read.All
AuditLog.Read.All
UserAuthenticationMethod.Read.All
Reports.Read.All

2. Check Scan Logs

View the scan details in the TrueConfig dashboard. The scan log shows which API calls succeeded or failed, helping identify specific data gaps.

3. Reconnect Tenant

If permissions were recently changed, disconnect and reconnect the tenant to trigger a fresh OAuth consent flow. This ensures TrueConfig has current, valid tokens.

4. Check Entra ID License

Some features require specific licenses:

Sign-in activity: Requires Entra ID P1/P2
PIM data: Requires Entra ID P2
Risky users: Requires Entra ID P2

Graceful Degradation

TrueConfig continues scanning even when some API calls fail. Controls that can't be evaluated due to missing data will show "Not Applicable" or "Data unavailable" status rather than failing the entire scan.

Token Refresh Failures

Problem

Scan fails with "Token refresh failed", "Invalid credentials", or "Authentication failed"

Causes

Expired client secret: The app registration client secret has expired
Revoked admin consent: A Global Admin revoked consent for TrueConfig permissions
Deleted app registration: The TrueConfig app registration was deleted from Entra ID
Disabled service principal: The app's service principal was disabled
Conditional Access blocking: A CA policy is blocking service principal authentication

Resolution

1. Check Client Secret Expiration

In Azure Portal, navigate to App Registrations → [Your TrueConfig App] → Certificates & secrets. Verify the client secret hasn't expired. If expired, create a new secret and update it in TrueConfig.

2. Verify Admin Consent

Go to App Registrations → [Your App] → API permissions. Ensure all permissions show green checkmarks indicating admin consent was granted.

3. Check Service Principal Status

In Entra ID → Enterprise applications → [Your App], verify "Enabled for users to sign-in" is set to Yes.

4. Reconnect Tenant

If issues persist, disconnect and reconnect the tenant in TrueConfig. This triggers a fresh OAuth flow and ensures tokens are properly issued.

Secret Rotation Reminder

Client secrets should be rotated every 90 days for security. Set a calendar reminder to rotate secrets before expiration to prevent authentication failures.