Gmail realtime troubleshooting — wizard error codes (administrator)

When the Gmail realtime setup assistant cannot enable push, it stops at the first failing validation step and shows a plain-language explanation, a suggested fix, an exact copy-paste command where one helps, and a link to the relevant Google documentation. This page lists each Gmail-specific error code the assistant can report, what it means, and how to clear it — so you can fix the problem and re-run validation.

When the Gmail realtime setup assistant cannot enable push, it stops at the first failing validation step and shows a plain-language explanation, a suggested fix, an exact copy-paste command where one helps, and a link to the relevant Google documentation. This page lists each Gmail-specific error code the assistant can report, what it means, and how to clear it — so you can fix the problem and re-run validation.

Available in: Pro. Gmail realtime push is part of the MailDesk Pro module; Basic always uses scheduled background sync and never shows these codes.

The one mistake that catches most people: project mismatch

Gmail requires the Pub/Sub topic to live in the same Google Cloud project as the OAuth client your mailbox authenticated with. If your topic is in a different project, Gmail refuses to watch it — even though the topic is perfectly valid and the IAM grant is correct.

This is the single most common avoidable failure. Before you start, confirm which project owns the OAuth client you connected the Gmail mailbox with, and run the setup script with PROJECT_ID set to that project. The setup assistant's WATCH_400_TOPIC_PROJECT_MISMATCH error (below) names the project Gmail expects in its detail line.

Webhook & audience errors

These come from MailDesk-side validation of your public URL and the OIDC audience — before Gmail is ever contacted. The webhook-reachability codes are covered on the Gmail realtime push setup page; the Gmail-specific audience one is below.

AUDIENCE_MISMATCH — OIDC audience does not match the webhook URL

What it means. Pub/Sub signs every push with an OIDC token whose aud claim must equal the URL the message is delivered to. MailDesk has different values for the saved audience and the computed webhook URL.

Fix. Re-run the wizard so MailDesk re-aligns both to <web.base.url>/maildesk/push/gmail. On the Google Cloud side, update the push subscription's audience to match.

There is no copy-paste command for this one — re-running validation re-saves the audience for you. Google reference: Authenticate push subscriptions.

Signer service-account errors

SIGNER_BAD_FORMAT — signer service-account email is malformed

What it means. The OIDC signer service-account email must look like <sa-name>@<project-id>.iam.gserviceaccount.com (all lowercase). The value you pasted does not match that shape.

Fix. Confirm the service account exists and copy its full email — no display name, no leading or trailing spaces.

gcloud iam service-accounts list

Google reference: Service account overview.

Gmail users.watch errors

These come from Google's users.watch call — the final validation step, run only when you click Enable Realtime. The assistant maps Google's HTTP status to the typed codes below.

WATCH_403_TOPIC_IAM_MISSING — Gmail cannot publish to your Pub/Sub topic

What it means. Google's Gmail publisher service account ([email protected]) does not have roles/pubsub.publisher on your topic. Without this grant, Pub/Sub refuses to forward new-email events.

Fix. Grant the role in your project. The setup script does this automatically; you can also run the command below manually (adjust the topic name if you changed it from the default maildesk-gmail-push):

gcloud pubsub topics add-iam-policy-binding maildesk-gmail-push \
  --member='serviceAccount:[email protected]' \
  --role='roles/pubsub.publisher'

Google reference: Pub/Sub publisher role.

WATCH_403_GMAIL_API_NOT_ENABLED — Gmail API is not enabled in your project

What it means. The Gmail API has never been used in this project, or it has been disabled. users.watch cannot run until you enable it.

Fix. Enable the Gmail API in your project, then retry after 30–60 seconds:

gcloud services enable gmail.googleapis.com pubsub.googleapis.com

Google reference: Enabling and disabling services.

WATCH_400_BAD_TOPIC — topic name is malformed

What it means. Gmail rejected the topic identifier. The expected shape is projects/<project-id>/topics/<topic-name> — slash placement matters.

Fix. Read the full topic resource name from gcloud and paste it back into the wizard:

gcloud pubsub topics describe maildesk-gmail-push --format='value(name)'

Google reference: Create a push subscription.

WATCH_400_TOPIC_PROJECT_MISMATCH — topic is in the wrong Google Cloud project

What it means. Gmail requires the Pub/Sub topic to live in the same project as your OAuth client. Your topic is in a different project, so Gmail refuses to watch it. The detail line in the assistant names the project Gmail expects (your OAuth client's project). This is the project-mismatch lesson above.

Fix. Re-run the setup script with PROJECT_ID set to that project so the topic is created there, then paste the new topic name back into the wizard. To switch the active project first:

gcloud config set project <oauth-client-project>

Google reference: Create a push subscription.

WATCH_404_TOPIC_NOT_FOUND — Pub/Sub topic does not exist

What it means. The topic name in the wizard does not match any topic in your project. Either it was deleted on the Google Cloud side, or the name has a typo.

Fix. List your topics, then either recreate the missing one with the setup script or paste the correct existing name back into the wizard:

gcloud pubsub topics list --format='value(name)'

Google reference: Create a push subscription.

OAuth / scope errors

These mean the mailbox's stored Google authorization cannot register a watch. They are fixed in MailDesk, not in Google Cloud — reconnect the mailbox.

WATCH_400_OAUTH_SCOPE_MISSING — OAuth scope does not cover users.watch

What it means. Your stored Gmail OAuth refresh token was issued with a scope set that excludes gmail.modify (or gmail.readonly + gmail.metadata), so users.watch is denied.

Fix. Disconnect and reconnect the Gmail mailbox under Settings → Mailboxes, accepting all requested scopes. There is no gcloud command for this — it is an OAuth reconsent.

Google reference: Gmail API OAuth scopes.

WATCH_401_OAUTH_INVALID — OAuth credentials invalid or expired

What it means. The OAuth refresh token MailDesk stores for this mailbox is no longer accepted by Google — typically because it was revoked at the user's Google account, the OAuth client secret was rotated, or the token aged out after a long idle period.

Fix. Open Settings → Mailboxes → and click Reconnect. Re-consent the OAuth flow, then re-run validation. No gcloud command applies.

Google reference: Gmail API OAuth scopes.

If you see an error code that is not listed here

The assistant can also report a generic WATCH_UNKNOWN_<status> when Google's users.watch returns a response shape MailDesk has not seen — often a transient 5xx that clears on retry. Retry once after about 30 seconds. If the same error keeps appearing, open the Odoo server log for the exact response body (MailDesk caps it to 500 characters) and file an issue.

Webhook-reachability and public-URL codes (WEBHOOK_URL_UNSET, WEBHOOK_URL_NOT_HTTPS, WEBHOOK_UNREACHABLE_DNS, WEBHOOK_UNREACHABLE_TIMEOUT, WEBHOOK_UNREACHABLE_TLS, WEBHOOK_UNEXPECTED_STATUS) are covered on the Gmail realtime push setup page, because they are about your server's public address rather than Gmail.

Quick reference

Throughout all of these, fallback polling keeps delivering mail. Push only ever makes mail arrive sooner.

Related

• Gmail realtime push setup — the guided setup assistant, including public-URL and webhook-reachability requirements
• Realtime troubleshooting — emails missing or delayed — general timing and recovery
• Gmail OAuth setup — connect or reconnect the mailbox