GoogleHelpit_
$ workspace --fix

# Workspace Troubleshooting

The problems that eat Workspace admins alive: DNS, email auth, deliverability, lockouts, SSO, sharing, migration. Symptom → cause → fix → official help.

all domain / dns spf / dkim / dmarc gmail delivery admin console recovery / security sso / saml drive / sharing migration calendar / meet mdm groups / chat vault / retention directory sync billing
// no matching fixes — try a different term or category.

🌍 Domain & DNS setup

▸Domain won't verify / "We couldn't verify your domain"
Cause
The google-site-verification TXT record was added incorrectly (extra characters, wrong host field), or DNS hasn't propagated.
Fix
Paste the exact TXT value into the host/@ record at your registrar; leave old records intact; allow up to 72 hours, then click Verify again. Use the setup tool's registrar-specific instructions.
Docs
verify your domain · DNS basics
▸Gmail not receiving mail / MX records wrong
Cause
MX records still point to the old mail host, or priorities/values are malformed. Mail must route to Google's servers.
Fix
At your registrar, replace existing MX records with Google's MX host (single smtp.google.com, priority 1 on new setups); delete legacy MX entries; allow up to 72 hours; activate Gmail from the setup tool.
Docs
set up MX records · record values
▸Multiple / conflicting TXT or verification records left in DNS
Cause
Old provider verification or SPF records not removed, causing lookup failures.
Fix
Keep only one SPF record; remove obsolete verification TXT records once verified — but leave the Google verification record (removing it can un-verify the domain).
Docs
support.google.com/a/answer/2716802

✉️ Email authentication (SPF / DKIM / DMARC)

▸SPF failing or "too many DNS lookups" (permerror)
Cause
No SPF record, more than one SPF record, or exceeding the 10 DNS-lookup limit from many include: statements.
Fix
Publish a single TXT record and merge all senders into it:
v=spf1 include:_spf.google.com ~all
Flatten/reduce includes to stay under 10 lookups. SPF needs no Admin console action; allow up to 48 hours.
Docs
support.google.com/a/answer/33786
▸DKIM not signing / "DKIM = neutral (no signature)"
Cause
DKIM was never generated/enabled in the Admin console, or the DNS TXT key wasn't added at the host.
Fix
Admin console → Apps → Google Workspace → Gmail → Authenticate email → Generate new record (2048-bit); add the TXT record at your host; return and click Start authentication.
Docs
support.google.com/a/answer/174124
▸DMARC rejecting your own mail / DMARC failures
Cause
DMARC policy (p=quarantine/reject) enforced before SPF and DKIM were aligned and stable.
Fix
Set up SPF and DKIM first and let them authenticate for at least 48 hours; start DMARC at p=none with a rua= reporting address; tighten to quarantine/reject after reviewing reports.
Docs
set up DMARC · troubleshoot

📨 Gmail delivery problems

▸Outbound mail lands in recipients' spam
Cause
Missing SPF/DKIM/DMARC, missing PTR (reverse DNS), or a high spam-complaint rate. Since Feb 2024 Gmail enforces sender guidelines.
Fix
Set up SPF or DKIM (both if bulk), valid forward+reverse DNS, one-click unsubscribe for bulk mail, and keep the Postmaster Tools spam rate under 0.3%.
Docs
sender guidelines · FAQ
▸Legitimate inbound mail marked as spam
Cause
Sender fails authentication or matches spam patterns; no allowlist configured.
Fix
Admin console → Apps → Gmail → Spam, phishing, and malware → add trusted domains to an allowlist / approved-senders list. Avoid over-broad allowlisting (spoofing risk).
Docs
a/answer/60752 · approved senders
▸"Message blocked" / 550-5.7.1 or 421 rejections
Cause
Sender flagged for suspicious/bulk activity, failed authentication, or hit a sending limit.
Fix
Verify the account isn't compromised, confirm SPF/DKIM, reduce send rate, and review the bounce code; use SMTP relay properly for app/bulk mail.
Docs
error reference · SMTP relay
▸"You have reached a limit for sending mail"
Cause
Exceeded Workspace daily recipient/message caps (e.g. ~2,000 external recipients/day) — often from a mass mailing or a compromised account.
Fix
Wait ~24 hours for the limit to reset; split large sends across days; use Google Groups or a bulk/SMTP-relay solution; check for compromise.
Docs
sending limits
▸App / printer / scanner can't send via SMTP
Cause
Devices using the old smtp.gmail.com + password fail once Less Secure Apps is off; or SMTP relay isn't configured for the sending IP.
Fix
For a single account, use an app password (requires 2SV) with smtp.gmail.com:587. For org devices/apps, set up the SMTP relay service (Apps → Gmail → Routing) allowlisting the static IP; use smtp-relay.gmail.com.
Docs
send from a device/app · SMTP relay

🛠️ Admin console basics (users, groups, OUs, licensing)

▸Can't add a user / "You've used all your licenses"
Cause
On an Annual/Fixed-Term plan you can't exceed purchased licenses without buying more.
Fix
Buy more licenses (Billing → Subscriptions) or free one by deleting/suspending an unused account, then add the user in Directory → Users.
Docs
add a user · licensing
▸Settings not applying to a subset of users
Cause
The policy is set at the wrong organizational unit (OU); child OUs inherit unless overridden.
Fix
Create/select the correct OU, move users there (Directory → Users → Change organizational unit), and apply the setting at that OU. Allow up to 24 hours to propagate.
Docs
add an OU · OU structure
▸Group vs. OU confusion (permissions not behaving)
Cause
OUs control service/policy settings; Groups control access and mailing — admins often conflate them.
Fix
Use OUs for policies, Groups for access/distribution. Add members in Directory → Groups; consider access groups for cross-OU service control.
Docs
groups · access groups

🔒 Account recovery & security

▸Locked out of the only super admin account
Cause
No secondary super admin and no/outdated recovery options.
Fix
Use the admin recovery flow at the sign-in page; if that fails, use the domain-verification recovery form (add a CNAME/TXT to DNS to prove ownership). Always keep 2+ super admins.
Docs
support.google.com/a/answer/33561
▸Admin can't self-reset password
Cause
Super admin password recovery is disabled, or recovery email/phone is missing.
Fix
Have another super admin reset it in Directory → Users; enable "Allow super administrators to recover their password"; add recovery email/phone for all admins.
Docs
a/answer/9436964 · recovery info
▸Users locked out after 2-Step Verification enforced
Cause
2SV was enforced before users enrolled, or a user lost their second factor.
Fix
Set an enrollment grace period before enforcing; admins can generate backup codes (Directory → Users → Security) or move the user to an OU where 2SV isn't yet enforced.
Docs
avoid lockouts · recover
▸Deploying 2SV / security keys without mass lockouts
Cause
Rushed enforcement without user enrollment causes mass lockouts.
Fix
Announce, allow enrollment, then enforce per-OU (Security → Authentication → 2-Step Verification). "Only security key" mode blocks self-service backup codes — the admin must issue them.
Docs
deploy 2SV · overview
▸Suspicious login / a user account was compromised
Cause
Phished or reused password; attacker may have added forwarding rules, app passwords, or recovery changes.
Fix
Suspend or reset the user (Directory → Users), sign out all sessions, then investigate: revoke app passwords/OAuth tokens, remove rogue mail filters/forwarding, check the Security Investigation/audit logs, and re-enable after cleanup.
Docs
secure a compromised account

🪪 SSO / SAML integration

▸"app_not_configured_for_user" / SAML app error
Cause
The user isn't assigned/provisioned to the SAML app, or the NameID doesn't match a Workspace username.
Fix
Ensure the IdP sends the primary Workspace email as NameID; assign the app to the correct OU/users; verify ACS URL and Entity ID match.
Docs
SAML errors · custom SAML app
▸SSO login fails: certificate or clock errors
Cause
The IdP signing certificate doesn't match the public cert uploaded to Google, or the IdP server clock is skewed (assertion outside the valid time window).
Fix
Re-upload the current IdP certificate; sync the IdP clock to reliable NTP; ensure responses are unencrypted (Google accepts unencrypted SAML only).
Docs
SSO troubleshooting · FAQ
▸Admin locked out of console by SSO
Cause
SSO applies to admins too, and the IdP is misconfigured or down.
Fix
Sign in via the super-admin SSO-bypass URL to reach the console and fix the profile; always keep an SSO-exempt super admin.
Docs
set up SSO · troubleshoot

📂 Drive & sharing

▸External sharing blocked / "You can't share outside your organization"
Cause
Admin external-sharing policy restricts sharing beyond the domain (default for some tiers/edu).
Fix
Admin console → Apps → Google Workspace → Drive and Docs → Sharing settings; set external sharing per OU (allowlisted domains, warnings, etc.).
Docs
support.google.com/a/answer/60781
▸"Shared drive is full" — can't add/edit files
Cause
The shared drive hit its storage limit, or org pooled storage is exhausted.
Fix
Delete/move files, raise the shared drive's limit (Apps → Drive → Manage shared drives), or add storage. Review org-wide usage in Storage.
Docs
shared drive limits · review storage
▸Files owned by a departing employee become inaccessible
Cause
My Drive files are owned by the individual; deleting the account can orphan them.
Fix
Before deleting, transfer ownership (the Directory → Users delete flow offers data transfer), or store team files in shared drives (org-owned) from the start.
Docs
manage shared drives · set up shared drives

🚚 Data migration

▸Data Migration Service (IMAP) fails to connect
Cause
IMAP disabled on source or destination, wrong server/port, or an app-specific password is required (accounts with 2FA).
Fix
Enable IMAP on both sides; use the correct IMAP host/port; generate an app-specific password on the source; run as a super admin.
Docs
a/answer/14792325 · new DMS
▸Migration is slow / hits the 100-user batch limit
Cause
DMS migrates up to 100 IMAP users per batch and throttles large mailboxes.
Fix
Split users into batches of ≤100 (CSV for >20 users); run overnight; migrate additional folders/users in a new job.
Docs
DMS FAQ · product matrix

📅 Calendar & Meet

▸External guests can't join a Meet / stuck in the waiting room
Cause
Only the meeting host (same domain) can admit external participants, and they must be present; admin policy may restrict external join.
Fix
Ensure the host is on the call to admit guests; Admin console → Apps → Google Meet → allow users to join meetings from outside the org / external participation.
Docs
Meet admin settings
▸Can't record a meeting / no record button
Cause
Recording not enabled by admin, user on an unsupported edition, using mobile, or Drive is full.
Fix
Admin console → Meet → Meet video settings → Recording → "Let people record their meetings"; use a computer; ensure the organizer's Drive has space.
Docs
turn on recording · troubleshoot
▸Calendar invites not reaching external guests / free-busy not visible
Cause
External sharing for Calendar is restricted, or guest-invite permissions are limited by policy.
Fix
Admin console → Apps → Google Calendar → Sharing settings → set external sharing (free/busy or full details) and allow inviting external guests.
Docs
known Meet issues

📱 Mobile device management (MDM)

▸Users prompted to enroll device / can't access work mail on mobile
Cause
Basic or Advanced mobile management is on, requiring enrollment/screen lock before account sync.
Fix
Choose Basic (screen lock + remote account wipe, no agent) vs. Advanced (full policies, app management, requires the Google Device Policy app and, for iOS, an Apple push cert). Set in Devices → Mobile & endpoints → Settings → Universal.
Docs
Basic · Advanced
▸iOS devices can't be managed / "Advanced" option greyed out
Cause
No Apple Push Notification service (APNs) certificate configured.
Fix
Create/renew the Apple push certificate in the Admin console (renew annually — expiry breaks iOS management), then enable Advanced management.
Docs
compare features · endpoint overview

💳 Billing & subscriptions

▸Charged more than expected / can't reduce licenses mid-term
Cause
On the Annual/Fixed-Term plan you commit to a license count for the term; reductions only apply at renewal. The Flexible plan bills monthly and prorates.
Fix
To lower the count on Annual, set "Auto-renew with fewer licenses" before renewal; for month-to-month flexibility switch to the Flexible plan (Billing → Subscriptions).
Docs
compare plans · reduce licenses
▸Need more seats immediately
Cause
Ran out of purchased licenses on either plan.
Fix
Billing → Subscriptions → your plan → add/purchase licenses (Annual lets you add anytime; billed prorated for the remaining term).
Docs
purchase more · understand bills
▸Free trial ended / subscription suspended for non-payment
Cause
No payment method added before trial end, or a failed charge.
Fix
Billing → set up/update the payment method; resolve the outstanding charge to reactivate. Data is retained for a grace period before deletion.
Docs
set up billing · flexible plan

💬 Groups & Chat

▸Group isn't receiving external email
Cause
The group's Who can post permission excludes people outside the org, or "Allow external members / posting from the web" is off.
Fix
In the group's settings (Groups for Business / Admin console → Directory → Groups), set Who can post to include "Anyone on the web" (or specific external senders) and enable external posting. Watch spam exposure.
Docs
group access settings · manage groups
▸Members can't post / messages held for moderation
Cause
Posting permissions are too tight, or message moderation is set to hold everything.
Fix
Adjust Who can post and the moderation policy in the group's settings; approve pending messages from the moderation queue.
Docs
a/answer/167430
▸Can't chat/Space with people at another company
Cause
External chat is off, or the other org restricts it — external Chat requires both sides to allow it.
Fix
Admin console → Apps → Google Chat → configure external chat (allow all domains or allowlist trusted ones). Both organizations must permit it.
Docs
external chat settings

🗄️ Vault & retention

▸A deleted user's mail/Drive data disappeared before it could be exported
Cause
Deleting an account purges its data after a short recovery window unless a Vault hold or retention rule preserved it.
Fix
Place a Vault hold (or transfer the data / keep the account suspended) before deleting. Recently deleted users can sometimes be restored within ~20 days (Directory → Users → Recently deleted).
Docs
Vault holds · restore a deleted user
▸Retention rule is deleting mail users still need
Cause
A default/custom Vault retention rule expires data after N days; without a longer hold, messages get purged on schedule.
Fix
Review Vault → Retention; a hold always overrides a retention rule (data is kept while held). Set custom rules per OU/date carefully — expiration is destructive.
Docs
retention overview · holds vs retention

🔗 Directory sync & provisioning

▸Google Cloud Directory Sync (GCDS) isn't creating/updating users
Cause
LDAP search rules don't match the intended OU, exclusion rules are too broad, or the sync ran in simulate-only mode.
Fix
Run a simulation and read the proposed changes first; fix the LDAP org-unit/search filters; confirm you're not in simulate mode for the real run; check the GCDS logs for the skipped-user reason.
Docs
about GCDS · troubleshoot GCDS
▸Sync accidentally suspended/deleted a batch of users
Cause
A source-directory change (or a wrong filter) made GCDS think users no longer exist, triggering suspend/delete on the next sync.
Fix
Set deletion policy to suspend (not delete) and cap the number of deletions per sync as a safety limit; always review the simulation diff before applying large changes.
Docs
GCDS troubleshooting
Beginner survival kit: keep 2+ super admins with recovery email/phone before enforcing any security policy · DNS changes take up to 48–72 hours — add DKIM/SPF before DMARC · use OUs for policies, Groups for access/mail · store team files in shared drives to avoid orphaned files · place a Vault hold before deleting anyone whose data matters.