# Troubleshooting

> Find the likely cause and the fix for common symptoms in Octiga, grouped by area.

When something in Octiga isn't behaving as you expect, find the symptom below for its usual cause and fix.

## Connection

### A tenant is stuck at Registering

**Cause:** A newly connected tenant goes through role assignment, propagation and an initial full sync before it becomes Active. This normally takes minutes, not seconds.

**Fix:** Give it a little longer. If the tenant is still Registering well after connecting, contact support with the tenant's name.

**See also:** [Connect a tenant](https://docs.octiga.io/start-here/connect-a-tenant/), [Tenants and dashboard](https://docs.octiga.io/tenants/tenants-and-dashboard/).

### Consent was denied, or the wrong Microsoft account consented

**Cause:** The admin who opened the consent link declined it, or signed in with an account that isn't a Global Administrator of the tenant you meant to connect.

**Fix:** Send the consent link again, and ask the person opening it to check they're signed in as a Global Administrator of the right tenant before approving.

**See also:** [What Octiga needs from your tenant](https://docs.octiga.io/reference/what-octiga-needs-from-your-tenant/), [Connect a tenant](https://docs.octiga.io/start-here/connect-a-tenant/).

### The connection beacon shows disconnected or unreachable

**Cause:** Octiga's last health check for this tenant couldn't reach Microsoft Graph, the management application's service principal or Exchange Online sign-in.

**Fix:** This usually clears on its own at the next check. If it doesn't, check that the client hasn't revoked Octiga's application in Microsoft Entra, and that none of the directory roles listed in [What Octiga needs from your tenant](https://docs.octiga.io/reference/what-octiga-needs-from-your-tenant/) have been removed.

**See also:** [Tenants and dashboard](https://docs.octiga.io/tenants/tenants-and-dashboard/).

### Exchange sign-in is failing after connection

**Cause:** The health check's Exchange Online sign-in probe is failing. It's one of the three checks behind a disconnected beacon.

**Fix:** Check that the management application still holds its Exchange Administrator role and hasn't been blocked in Exchange Online.

**See also:** [Tenants and dashboard](https://docs.octiga.io/tenants/tenants-and-dashboard/).

## Sync

### Data looks stale

**Cause:** Octiga syncs on a schedule, not continuously. Directory objects and tenant-wide settings normally reflect a change within about an hour; mailbox and authentication details within about two hours, when event monitoring is on. A tenant without a usable audit-event signal runs on a slower, polling-only schedule.

**Fix:** Wait for the next sync cycle. Octiga doesn't offer a way to force an immediate sync.

**See also:** [Events](https://docs.octiga.io/monitoring/events/).

### A change made directly in Microsoft 365 hasn't appeared

**Cause:** A change made directly in Microsoft 365, rather than through Octiga, is picked up at the next sync for that resource, or sooner where Octiga receives Microsoft's change notifications for it.

**Fix:** Give it a sync cycle. A change made through Octiga itself (a save or a remediation) refreshes immediately, because Octiga re-checks what it has just written.

**See also:** [Deviations](https://docs.octiga.io/baselines/deviations/).

## Monitoring health

### Audit log off

**Cause:** The Unified Audit Log is switched off in the client tenant, so Microsoft isn't recording the events Octiga collects.

**Fix:** Turn it on, either by deploying the Unified Audit Log baseline or directly in Microsoft Purview.

**See also:** [Events](https://docs.octiga.io/monitoring/events/), [Remediation](https://docs.octiga.io/baselines/remediation/).

### Not subscribed

**Cause:** The tenant is reachable and auditing, but the Microsoft 365 Management API subscriptions that feed Octiga aren't in place, so no events are being collected.

**Fix:** This clears once the subscription is restored at the next check cycle. If it doesn't, contact support.

**See also:** [Events](https://docs.octiga.io/monitoring/events/).

### Status unknown (stale)

**Cause:** This tenant's last health check is too old to rely on, usually because it has dropped out of the regular six-hourly check cycle rather than because it missed a single run.

**Fix:** If the tenant stays in this state for more than a day or so, contact support.

**See also:** [Tenants and dashboard](https://docs.octiga.io/tenants/tenants-and-dashboard/).

### Tenant unreachable

**Cause:** At the last health check, Octiga couldn't reach Microsoft Graph, the management application's service principal or Exchange Online sign-in for this tenant.

**Fix:** This usually clears at the next check. If it doesn't, follow the fix for a disconnected beacon under Connection, above.

**See also:** [Tenants and dashboard](https://docs.octiga.io/tenants/tenants-and-dashboard/).

## Baselines and deviations

### A baseline never appeared after a deploy

**Cause:** The tenant, or the group or user it was deployed to, doesn't hold the Microsoft licence that baseline needs, so it was skipped for licence. That's a quiet exclusion, not a failure.

**Fix:** Check the deploy result's skipped count, then check [Licence requirements](https://docs.octiga.io/reference/licence-requirements/) for what that baseline needs.

**See also:** [Deploying a scheme](https://docs.octiga.io/baselines/deploying-a-scheme/).

### A user shows Excluded

**Cause:** The user doesn't hold the licence a baseline needs, so Octiga left them out of that baseline's checks rather than reporting them as failing.

**Fix:** Nothing needs fixing in Octiga. If you want the baseline evaluated for this user, assign them the licence.

**See also:** [Licence requirements](https://docs.octiga.io/reference/licence-requirements/), [Deviations](https://docs.octiga.io/baselines/deviations/).

### A deviation won't resolve even though the setting looks right

**Cause:** Deviations follow sync. A fix made directly in Microsoft 365 shows once the next sync (or the relevant change notification) reaches Octiga, not the moment you make it.

**Fix:** Give it a sync cycle before assuming the fix didn't take.

**See also:** [Deviations](https://docs.octiga.io/baselines/deviations/).

### A deploy result shows skipped items

**Cause:** Some of the incoming baselines couldn't be applied, most often because of licence and occasionally because a baseline doesn't apply to that scope.

**Fix:** Check the skipped count and reason on the deploy result; it shows what didn't land and why.

**See also:** [Deploying a scheme](https://docs.octiga.io/baselines/deploying-a-scheme/), [Licence requirements](https://docs.octiga.io/reference/licence-requirements/).

## Deploying

### Deploying a scheme says this tenant is managed by another scheme

**Cause:** A tenant can be managed by only one org-level scheme at a time, so deploying a different scheme detaches it from its current one.

**Fix:** If that's what you intend, confirm the detach; the deploy and the detach happen together, in one action.

**See also:** [Schemes](https://docs.octiga.io/baselines/schemes/), [Deploying a scheme](https://docs.octiga.io/baselines/deploying-a-scheme/).

### Deploying a Direct copy onto a Managed group clears its link

**Cause:** Deploying a scheme to a group with Copy and detach (Direct) changes how the group is governed. A group can't track one scheme's edits while also holding a hand-picked, untethered subset, so the change clears the existing link.

**Fix:** Check this is what you want before deploying. The group's own hand-added (group-direct) baselines are untouched either way.

**See also:** [Groups and priority](https://docs.octiga.io/baselines/groups-and-priority/), [Deploying a scheme](https://docs.octiga.io/baselines/deploying-a-scheme/).

## Signing in

### A valid Microsoft account can sign in but has no access

**Cause:** Access to Octiga comes from group membership, and this account isn't in any access group yet.

**Fix:** Ask an Admin or L2 Support user to add the account to an access group. See [Access controls](https://docs.octiga.io/administration/access-controls/).

**See also:** [Roles and permissions](https://docs.octiga.io/start-here/roles-and-permissions/).

### A tenant you expect to see is missing

**Cause:** L1 Read and L1 Read/Write reach only the tenants assigned to their groups. This is enforced on the server, so a tenant outside your groups' assignment doesn't appear for you anywhere, including in your alerts.

**Fix:** Ask an Admin or L2 Support user to add the tenant to one of your groups.

**See also:** [Roles and permissions](https://docs.octiga.io/start-here/roles-and-permissions/), [Access controls](https://docs.octiga.io/administration/access-controls/).

### A settings section is missing from navigation

**Cause:** Octiga hides what your role can't reach rather than showing it disabled, so a missing section is one your role doesn't include.

**Fix:** Check [Roles and permissions](https://docs.octiga.io/start-here/roles-and-permissions/) for what each role can see. If you need more, ask an Admin to change your group's role.

**See also:** [Roles and permissions](https://docs.octiga.io/start-here/roles-and-permissions/), [Access controls](https://docs.octiga.io/administration/access-controls/).

## Alerts and PSA

### PSA tickets aren't being created

**Cause:** Usually one of two things: the severity you're alerting at has no priority mapped for that vendor (an empty priority means no ticket is filed), or the connection to the PSA is failing its health check.

**Fix:** Check the integration's priority mapping for the alert's severity, then check its connection status.

**See also:** [PSA integrations](https://docs.octiga.io/administration/psa-integrations/).