Troubleshoot Workspace governance
Resolve rollout, grant, Google connection, provisioning, audit, Slack, template, and mailbox-delegation problems.
Use the visible access, connection, job, and audit state to choose the narrowest recovery. Do not work around a grant failure with a stronger organization role, and do not broaden provider permissions merely to make a check pass.
You cannot open Workspace governance
The app is absent or returns not found
Confirm that workspace_governance is enabled for the organization. The rollout flag and the membership grant are separate gates. A grant cannot make an unflagged organization available unless the supported user-level rollout exception is present.
You are not authorized to access this page
Ask a current grant administrator to inspect your explicit Workspace governance grant for that organization. Organization-admin and platform-admin standing do not provide a bypass.
- Viewer opens the read-only governance pages and Settings, but cannot open Admin-only mailbox delegation or change state.
- Manager can govern topology, apply it, run audits, manage templates, and enforce Slack policy.
- Admin can additionally manage provider connections, schedules, and mailbox delegates.
A grant in one organization does not open another. Guests cannot receive this grant.
Google Workspace will not connect
| Symptom | Cause and recovery |
|---|---|
| The service account is not configured for this environment. | Ask the environment owner to configure the dedicated Workspace governance service account. Do not reuse the general cloud credential or another product’s account. |
| The marketplace app is not published yet. | This is the current product state. Expand Manual setup (if the marketplace app cannot be installed) and authorize the displayed client ID and complete scope list through Google Admin domain-wide delegation. |
| The service account could not access Google Workspace as this admin. | Confirm that the domain-wide delegation entry is saved, contains every displayed core scope, and that Workspace admin email belongs to a super admin in that workspace. |
| Could not connect. | Recheck the same delegation entry and admin email. Do not create a second entry with a partial scope list. |
| Connection test failed. | The token could not use at least one required surface. Check Drive access, shared-drive administrator access, Google Groups administrator access, and user-directory access. |
| A changed admin identity is rejected | The replacement must be a different super-admin email in a domain recorded for the connected workspace. |
Before changing the Google admin identity, make sure the replacement is either not a direct member or already Organizer on every governed, provisioned drive. The swap grants Organizer only when the replacement has no direct user permission; any existing direct permission, including a lower role, skips that grant, and the previous admin’s direct permission can still be removed. Correct a lower direct role in Google first. If permission listing, a required grant, or a revoke fails, the identity change remains saved; inspect every governed drive, verify the replacement is Organizer, and run G0 to find access that remains.
Import, Apply, or Audit does not finish cleanly
You have changes not yet applied to Google Workspace
This is a local desired-state warning. Review the drive, folder, group, and grant changes, then select Apply to Google. A local save does not itself prove that Google changed.
Apply completes with problems
Provisioning works only on governed resources. It creates or adopts intended resources and manages the permissions in its ledger. A partial problem does not stamp the topology as fully provisioned, so the pending-change prompt remains.
Resolve the first provider error, then apply again. Do not delete unknown Google permissions in an attempt to imitate the desired state; Workspace governance deliberately revokes only permissions it previously recorded as managed.
Audit shows Error
Treat Error as unavailable evidence, not as In sync. Restore provider access and run the audit again. A transient read failure can preserve earlier findings so that unavailable data does not silently clear a known problem.
Unmanaged resources keep appearing
The audit reports live drives or groups outside the governed topology. Use Import from Google when they should become observed records, then explicitly choose which ones to manage. Do not govern an unknown resource only to clear the count.
A policy check reports drift
| Finding | Recovery |
|---|---|
| Direct user access · G0 | Replace the direct permission with the approved group-based grant. Confirm the person retains intended access through that group before removing the direct path. |
| People directly in access groups · G1 | Add the person to the correct role group, verify the nested access path, then use the direct-member removal only in an approved change window. |
| Naming integrity · G2 | G2 checks the group email’s local-part prefix, not its display name. Rename group cannot clear this finding because the current rename flow leaves the email unchanged. Create or select an Access or External group whose email starts with the configured prefix, and add the intended drive or folder grant to that group. Select Apply to Google, run Audit now, and verify that the replacement provides the intended access. Only then, in an approved change window, remove the noncompliant grant. Select Apply to Google again, run Audit now again, and confirm that G2 clears. |
| External access (airlock) · G3 | Grant the external group only to an airlock drive that allows users outside the workspace domain. |
| Drive capacity · G4 | Reduce or restructure membership before hitting Google’s 100-group, 600-member, or 50,000-individual limits. Large indirect membership can also affect automatic drive visibility. |
| Drive hardening | Compare the drifted restriction with the approved drive policy before applying a change. Do not relax a control simply to produce In sync. |
Folder-template results are unexpected
- Existing folders did not change after a template edit. This is expected; edits apply to the next creation only.
- Existing folders remained after detach. This is expected; detaching never removes created folders.
- A yearly attachment exists but the current year is missing. Select Create year now or wait for the scheduled year-rollover job, depending on the approved workflow.
- A template cannot be attached. Confirm that the anchor is a folder in a governed drive, not an observed-only resource.
Slack inventory or enforcement is stale
Slack not connected
Open Settings and connect the governance app. The OAuth flow requires approval of both the bot and the connecting person’s admin authorization.
If the app is not configured for the deployment, a platform administrator must provision it. If Settings says the workspace still uses a previous app, select Reconnect Slack. If the token is revoked, the connection is marked for reconnection instead of continuing silently.
Audit reports no channels or members
Open Slack channels and select Audit now. The inventory is loaded by the audit, not by opening the page. If the provider call fails, preserve the error and reconnect when required.
Missing members are not added
Confirm all of the following:
- the policy has Auto-add missing members enabled;
- the audience resolves to current Slack identities;
- the channel is not archived;
- for a private channel, the bot is already able to enter it.
Exclusive only reports extra members. It never removes them automatically. Review and remove an extra member manually through an approved Slack process.
Member findings remain during a Google outage
This is deliberate. The Slack audit preserves prior directory mismatch evidence when Google is unavailable. Guest-expiration checks can still update. Restore Google directory access and run Slack audit again before resolving the old findings.
Mailbox delegation fails
Authorize the Gmail scope
The connected workspace has not authorized the optional Gmail scopes. Before editing the existing domain-wide delegation entry in Google Admin, copy that client-ID entry’s complete current scope list. The mailbox page’s Copy scope value contains only the two Gmail scopes; append them to the copied list and save the complete combined list. Confirm in Google Admin that the saved entry still contains every original scope plus both Gmail scopes.
Do not save the Gmail-only value. Saving replaces the whole delegated list, which would remove the core scopes used by drives, groups, and users. Everything else in Workspace governance keeps working while the optional Gmail scopes are absent.
An immediate Test connection can reuse the current access token, so Connection test passed. does not prove that the saved delegation entry is complete. Run the test after propagation as a supplemental check. If it fails, compare the saved entry with the complete list you copied and restore any missing core scopes. If the list is intact, follow Connection test failed. above instead of editing scopes again. After the test passes, return to mailbox delegation and select Show delegates.
The mailbox or delegate is rejected
- The mailbox must belong to a domain recorded for the connected workspace.
- The delegate must belong to the connected workspace and the same Google organization as the mailbox.
- Mail delegation must be enabled for the mailbox’s organizational unit in Google Admin.
- The Gmail API must be enabled for the service account’s Google Cloud project; this does not require changing the customer workspace.
A successful add does not appear immediately
Google creates mailbox delegation in the background. Wait a few minutes, then enter the mailbox and select Show delegates again. Do not submit repeated grants while propagation is pending.
A removed delegate still appears
Refresh the delegate list once. If the person still has access, record the exact mailbox, delegate, time, and visible error in an approved private support channel. Do not include mailbox contents.