---
title: "Gmail setup and troubleshooting"
description: "Configure a Google Desktop OAuth client, authorize a test user, and resolve common Gmail connection errors."
---

> Documentation Index
> Fetch the complete documentation index at: https://hafi-go-hands-free-docs.free-hero-8440.chatgpt.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail setup and troubleshooting

# Gmail setup and troubleshooting

Gmail connection requires a Google OAuth client ID and secret from the same Google Cloud project where the Gmail API is enabled.

## Set up Google Cloud

1. [Enable the Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com) in the Google Cloud project that owns the OAuth client.
2. Create an OAuth client with application type **Desktop app** in [Google Cloud Console](https://console.cloud.google.com/auth/clients).
3. Set `HAFI_GMAIL_CLIENT_ID` and `HAFI_GMAIL_CLIENT_SECRET` from that client in the environment where Hafi will run.
4. Connect using `bun run dev connect gmail --account personal` while running from source.

Hafi listens on `127.0.0.1` using a random available port for the browser callback. Do not register a fixed redirect URI for a Desktop app client.

## Add a test user while the OAuth app is in Testing

Open [Google Auth Platform > Audience](https://console.cloud.google.com/auth/audience) and add the exact Google account you will authorize under **Test users**. Use that account in the browser when running `bun run dev connect gmail`.

While the OAuth app remains in Testing, Google expires this authorization and its refresh token after seven days. Reconnect when authorization expires to continue scheduled use.

## Troubleshoot

| Error or symptom | Cause and resolution |
| --- | --- |
| `redirect_uri_mismatch` | A Web application client expects a fixed redirect URI. Create and use a **Desktop app** client from the same project instead. |
| `Error 403: access_denied` / available only to developer-approved testers | Add the exact account to **Test users** under Google Auth Platform > Audience, then authorize with that account. |
| Authorization stops working after several days | Testing-mode authorizations expire after seven days. Reconnect, or review the OAuth app's publishing and verification requirements with Google before production use. |
| Gmail API request fails | Confirm the Gmail API is enabled in the project owning the OAuth client, and that the ID and secret both belong to that project. |

Live Gmail account behavior and permissions still require end-to-end verification. See [Getting started](/getting-started) for the full setup sequence.

Source: https://hafi-go-hands-free-docs.free-hero-8440.chatgpt.site/gmail-setup/index.mdx