Applies to: any transport whose credentials resolve from a secret store
(SSM on the shipped AWS image; file:// on the reference binary).
Audience: on-call operators.
Risk: low to act — the resolver serves the last-known-good credential through
a transient backend blip; the work is fixing the source.
TEMPORARY_AUTH_FAILURE or NOT_AUTHORIZED.CredentialRefreshFailures or CredentialResolveFailure climb.CredentialStaleServed is non-zero — the resolver is serving an expired
last-known-good credential because the backend is unreachable.GoBridge/Runtime split cleanly
(monitoring.md#key-metrics):
CredentialRotationApplied — a rotation reached a live transport (success).CredentialRefreshFailures — a resolve failed during the rotation poll.CredentialResolveFailure (code) — a repository fetch failed, tagged with
the error code so a permission denial (NOT_AUTHORIZED) is distinguishable
from a backend outage (UNAVAILABLE).CredentialStaleServed (code) — the resolver returned an expired
credential after a retryable fetch error; a rising value means the secrets
backend has been unreachable longer than the cache TTL.TEMPORARY_AUTH_FAILURE — resolution succeeded but the broker reports
“auth not yet propagated”: a just-rotated credential not yet active, or
clock skew. Usually clears within seconds
(troubleshooting.md#temporary_auth_failure).CredentialResolveFailure{code=NOT_AUTHORIZED} — the bridge’s IAM role lost
read access to the secret; {code=UNAVAILABLE} — the backend is down.admin_api_key_param is mandatory. A rotation that
never lands often means the SSM parameter was updated under a different name
or the task role cannot read it.TEMPORARY_AUTH_FAILURE that persists: there is no HTTP “refresh”
endpoint. The bridge already re-resolves on its rotation poll and reconnects on
its own, so a persistent code means the broker keeps rejecting a credential that
DID resolve – usually clock skew or a value that is not yet active at the broker.
Verify clock sync (NTP) on the bridge host, confirm the rotated credential is
active at the broker/IdP, and if it outlasts the propagation window restart the
process to force a fresh resolve and a clean reconnect
(troubleshooting.md#temporary_auth_failure).CredentialResolveFailure{code=NOT_AUTHORIZED}: restore the IAM read grant
(or the file:// permissions) on the secret. Rotation resumes on the next poll.CredentialResolveFailure{code=UNAVAILABLE} / rising CredentialStaleServed:
the backend is unreachable. The bridge keeps running on the last-known-good
credential; fix the backend before the credential actually expires.