Hiro development journal

Diagnosing Hiro's Gmail authorization failure

2026.07.26 at 14:53:53 America/Los_Angeles Published Machine-readable JSON

Executive summary

The personal task dashboard's Gmail import returned a RefreshError during its first live authorization attempt.

The local OAuth configuration was inspected without exposing credentials. The credential and token files both exist, the saved authorization has the required read-only Gmail and Calendar scopes, a refresh token is present, and the OAuth client identities match.

A direct refresh request to Google's token service returned invalid_grant. This identifies the stored Google authorization as revoked or otherwise no longer renewable rather than a task-import, Gmail-label, or requested-scope defect.

No token was deleted or replaced. A fresh interactive Google authorization is the required recovery step.

Work completed

Credential configuration inspection

Completed

Confirmed that Hiro resolves both the Google OAuth client file and the saved authorization token at their configured local paths.
Confirmed that the saved token contains a refresh credential and the required Gmail read-only and Calendar read-only scopes.
Confirmed that the saved token belongs to the same OAuth client described by the configured client file.
Inspected only non-secret metadata and did not print, publish, copy, delete, or replace any credential value.

OAuth refresh diagnosis

Completed

Confirmed that the saved access token is expired and therefore requires refresh before the Gmail API can be called.
Sent a direct refresh request using the configured local authorization and captured Google's structured failure response.
Google returned invalid_grant with a generic Bad Request description. That response means the refresh credential is no longer accepted and cannot be repaired by retrying the import.

Decisions and reasoning

Do not alter Gmail scopes because the saved authorization already includes the required read-only scopes.
Do not retry imports repeatedly when Google reports invalid_grant.
Do not delete or overwrite the saved token until a fresh interactive authorization is intentionally initiated.
Keep the integration read-only; fresh consent should request only Gmail read-only and Calendar read-only access.

Validation and evidence

Check	Status	Result
OAuth file presence	passed	Both configured local OAuth files exist.
Saved authorization metadata	passed	The token contains a refresh credential, both required read-only scopes, and a client identity matching the configured OAuth client.
Google token refresh response	failed	Google rejected the refresh request with invalid_grant: Bad Request. This is the confirmed cause of the Gmail import failure.

Current state

Hiro's task and reading dashboard remains operational.
Gmail imports cannot run until the local Google account is authorized again.
The existing saved token remains in place and was not modified by this diagnosis.
The required recovery is an interactive Google sign-in and consent flow using the existing OAuth client.

Next steps

Initiate a fresh local Google OAuth flow and complete the account-owner sign-in and read-only consent.
Preserve the rejected token as a recoverable backup until the replacement authorization succeeds.
Retry a small labeled Gmail import and confirm that review-first ingestion and duplicate prevention operate correctly.
Improve the dashboard error message later so invalid_grant is presented as a clear reauthorization requirement rather than a generic RefreshError.