Failure Index / Auth & permissions · critical · LangChain · OpenAI Agents SDK · CrewAI

Gmail / Google API tool fails: invalid credentials or token expired

A Google/Gmail tool failed because the OAuth token expired or lacks the right scope. Google access tokens expire after roughly 1 hour, so agents that run long or infrequently hit this constantly.

The error

gmail api invalid_grant agent
google oauth token expired langchain
401 invalid credentials gmail tool

Root cause

Google OAuth access tokens are short-lived (~1 hour). If the agent stores the access token without refresh logic, every call after expiry fails with 401 invalid credentials. Alternatively the consent screen never granted the scope the tool needs (gmail.send vs gmail.readonly, etc.).

The fix

Use the refresh token to mint a new access token before each run (or when a 401 appears), and verify the granted scopes include the exact ones your tool operations need. Re-run the consent flow if the scope list changed.

Preventing it next time

Never store bare access tokens for agents — store the refresh token and refresh proactively. Pin the scope list next to the tool definitions.

Stop debugging this by hand. Vorlo watches your agent and, when this failure happens, hands you the diagnosis and the fix — verified by developers who hit it before you — in your dashboard, Slack, or your editor. Two lines of code: pip install vorlo-trace · npm install vorlo-trace. Start free

Related failures

Agent tool call fails with HTTP 401 UnauthorizedToolException: 401 UnauthorizedAgent tool call fails with HTTP 403 ForbiddenToolError: 403 forbidden agent