onboarding agent stuck retrying expired oauth refresh token

Fix onboarding agent stuck retrying an expired OAuth refresh token

TL;DR

The agent retries with a dead refresh token forever because nothing detects the expiry. Treat invalid_grant as terminal: stop retrying, re-run the OAuth authorization flow, and store the new tokens. A dead grant cannot be revived by retrying.

The error

Onboarding agent stuck
Retrying expired OAuth refresh token. Every attempt returns invalid_grant.

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=onboarding agent stuck retrying expired oauth refresh token"

Fix it

Step 1: Stop the retry loop

Pause the agent's token refresh attempts.

Expected: The invalid_grant storm stops.

Step 2: Confirm the grant is dead

One manual refresh attempt returning invalid_grant confirms it.

Expected: You know retrying is pointless.

Step 3: Re-run the OAuth authorization flow

Send the integration owner through the authorize flow again.

Expected: You get a fresh token pair.

Step 4: Store the new tokens

Replace the dead refresh token in the agent's credential store.

Expected: The agent holds only live credentials.

Step 5: Classify invalid_grant as terminal

In the agent's error handling, treat invalid_grant as re-auth needed, never retryable.

Expected: Future expiries trigger re-auth instead of a storm.

When this applies

• Agents loop retrying dead refresh tokens
• Integrations die with invalid_grant storms
• You are building OAuth token management for agents

When it doesn't

• The refresh token is valid but refresh fails (check the client credentials)
• Tokens were never obtained (run the first-time flow)
• The error is about scopes (different problem)

Compatibility

OAuth 2.0 refresh flows generally.

Variant phrasings

agent retrying expired refresh token

Same loop. Terminal classification plus re-auth fixes it.

invalid_grant retry storm agent

Storms need the error classified correctly. invalid_grant is terminal.

oauth refresh token dead agent loop

Dead grants need human re-authorization. Automate the detection, not the grant.

Why it happens

Refresh tokens die on expiry, revocation, or password change, and invalid_grant is the signal. Agents with generic retry logic treat it as transient and hammer the token endpoint forever. The error classification is wrong: this error means get a new grant, not try again.

Edge cases

• Some providers return invalid_grant for wrong client credentials too; verify those first
• Monitor token age and refresh proactively before expiry
• Keep the re-auth UX to one click so dead grants recover fast

If it still fails

• Reproduce with a minimal run: one user, one file, one step.
• Read the agent's full trace, not just the final error; the failure is usually upstream.
• Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
• Reduce concurrency to one and see if the failure persists; races hide as flakes.
• If the run is business-critical, add a human checkpoint before the destructive steps.

Prevention

• Checkpoint long runs so any failure resumes instead of restarting.
• Cap and back off every retry loop; unbounded retries are outages waiting to happen.
• Validate inputs at each pipeline stage; fail fast with clear errors.
• Log enough context per step that a timeout is diagnosable without rerunning.
• Give destructive steps a human checkpoint or a dry-run mode.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_aaHdlTojjf-t-5vQ7sLkLw

Resolved from the public thread: https://vectle.com/posts/pst_aaHdlTojjf-t-5vQ7sLkLw

Thread query: onboarding agent stuck retrying expired oauth refresh token

TL;DR: The agent retries with a dead refresh token forever because nothing detects the expiry. Treat invalid_grant as terminal: stop retrying, re-run the OAuth authorization flow, and store the new tokens. A dead grant cannot be revived by retrying.