Report Ingestion Troubleshooting

Report Ingestion Troubleshooting

First sync fails right after setting the mailbox address

Expected if the two Microsoft-side consent steps aren't done yet — setting the mailbox address is the more discoverable action, so this ordering is common. The dashboard shows the same consent-guidance links directly next to the sync error:

1. Mail access consent: the organization's Global Admin must click the mail-access admin-consent link and approve it (grants the app's Mail Access application, app-only Mail.Read, permission in the tenant).
2. Limit the app to the reports mailbox (done outside this app, in Exchange Online PowerShell, with RBAC for Applications or an Application Access Policy) — this is the step that matters for security: without it, an app-only Graph token for Mail.Read can read any mailbox in the tenant, not just the shared one. With RBAC for Applications, a sync that worked and then fails after you removed the Entra grant means the Exchange role assignment isn't active yet (it can take up to 2 hours) or its scope doesn't include the reports mailbox.

Full commands for both → Onboarding Your First Organization step 3.

Consent steps are done, but sync still isn't confirmed

Click "Resync now" (or wait for the next scheduled poll, every 10 minutes). As platform admin, /admin/job-runs shows every mailbox-poll attempt across all organizations — a success row for this org's mailbox_poll job confirms it end-to-end, and doubles as confirmation the scoping is correct (a mis-scoped policy or role assignment fails here, not silently). Run Test-ServicePrincipalAuthorization (RBAC for Applications) or Test-ApplicationAccessPolicy again if that row keeps failing.

No reports ingested at all, from any organization

Check ENTRA_MAIL_CLIENT_ID/ENTRA_MAIL_CLIENT_SECRET are set — both ways of ingesting reports (an org's own mailbox, and the operator-hosted mailbox) go through this one app registration. Unset, the dashboard still runs fine and does DNS checks, but nothing is ever ingested. See Configuration Reference.

A specific report arrived but doesn't show up

Two causes, both logged by the worker:

• The report sender check left it out. The domain's Reports or TLS reports page shows a "left out" notice; Review lists each report and why. See Forged reports and sender verification for the setting that decides this.
• It was forwarded to a hosted address instead of sent to it directly — counted as unmatched in the hosted reports poll log line. See Which organization a report belongs to.

---

← Troubleshooting & FAQ · Home