auth token expired mid-scheduled refresh run: agent failed with error 401 unauthorized

TL;DR

Make the run renew its own credentials. Note that for this integration the Tableau REST API signs in with a personal access token or credentials and returns a session token scoped to a site, so any run longer than the token lifetime is guaranteed to expire unless the client refreshes. Add an expiry aware refresh before calls, a single re-authentication and retry on a 401 response, and checkpointing so the retried step does not duplicate work. The dashboard build itself is rarely at fault.

auth token expired mid-scheduled refresh run: agent failed with error 401 unauthorized

Use this when

• Run logs show successful calls followed by 401 responses starting at a consistent elapsed time.
• Short test runs of the same task succeed while full builds fail.
• The partial dashboard exists in the target system after the failed run.

Not for this skill when

• The very first API call returns 401. The stored credentials themselves are wrong or revoked, so fix the configuration.
• Calls return 403 after authenticating fine. That is a permission scope problem, not an expiry problem.

Steps

1. Measure the elapsed run time at the first 401 and compare it with the documented token lifetime for the integration. Verify: the failure time lines up with the token expiry window
2. Confirm how the client obtains its token, noting that the Tableau REST API signs in with a personal access token or credentials and returns a session token scoped to a site. Verify: the client code path for token acquisition is identified
3. Add proactive refresh, where the client checks token age before each step and re-authenticates before expiry. Verify: a test run longer than the token lifetime completes without a 401
4. Add a reactive path that treats a single 401 as a signal to re-authenticate once and retry the step, while repeated 401 responses fail the run clearly. Verify: an artificially expired token mid run is recovered by the retry path
5. Make retried write steps idempotent or read back first, so the post refresh retry cannot duplicate a dashboard or chart. Verify: forcing a retry on a completed step leaves exactly one object
6. Rerun the full original task and confirm completion, then review the run log for any remaining 401 entries. Verify: the run finishes with no unrecovered authentication failures

Why it happens

Expiry mid run is a scheduling fact, not an error in the task. Clients that acquire a token once at startup implicitly assume the run is shorter than the token, an assumption long agent builds break. Expiry aware clients, proactive refresh plus one reactive retry, are the standard pattern for any long running automation, and checkpointing keeps the recovery from corrupting the partial work that preceded it.

Agent builds against the Tableau REST API often run longer than the access token lifetime, because they wait on renders, polls and slow writes. The run starts authenticated, works happily, and then every call starts returning 401 at the same wall clock moment. Because the failure arrives mid build, the partial dashboard state is real, and a naive restart duplicates the early steps. Token lifetime, not dashboard content, decides which runs fail, which is why shorter test runs pass and full builds fail.

Operational notes for authentication failures in agent pipelines. Record token acquisition and refresh events in the run log with timestamps but never with token values, because the timing pattern is the diagnostic and the value is a liability. A run that shows a refresh immediately before recovery proves the design works, while a run with no refresh events at all explains itself. Token lifetime should also be written in the runbook for each integration, since the number differs by provider and by app type and nobody remembers it during an incident.

Credential ownership for agents should be explicit and boring. Each integration gets a named service identity where the provider supports it, a named human owner, and a rotation date in the team calendar. Agent authentication incidents become long when the credential belongs to a departed individual or an unknown app registration, because revoking or renewing it might break something nobody can enumerate. The register of which runs use which identity is what turns a scary 401 into a routine renewal.

Variants and edge cases

401 unauthorized mid run token expired agent Tableau

The near verbatim phrasing from the run failure.

long agent run outlives access token refresh pattern

The design variant for expiry aware clients.

agent build fails after one hour Tableau token lifetime

The duration clue variant where only long runs fail.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ABZrNCFDzpeUKnADGcXJuw