Unknown token: access token is invalid or expired

I'm seeing the error Unknown token: access token is invalid or expired. What should I do?

This error (M_UNKNOWN_TOKEN) means the homeserver has rejected your access token for every authenticated request — sync, verification, and media all fail at once. Relay tries proactive token refresh to prevent this, so a recurring occurrence usually points to a token-refresh problem worth investigating.

Troubleshooting Steps

Capture the logs

Run this in a terminal while using Relay (or use Console.app with the same filter):

/usr/bin/log stream --predicate 'subsystem == "app.subpop.MatrixKit" OR subsystem == "app.subpop.Relay"' --level debug

Relay's own diagnostics appear under the subsystem app.subpop.Relay; it's useful to look for Relay's messages alongside the MatrixKit ones.

What to look for

The sequence below tells you which failure mode you're hitting:

Log evidence	Likely cause
No refresh calls at all before the error	Proactive refresh isn't running, or the server issued no refresh token at login (non-refresh-capable server or password login path).
Refresh calls succeed (Session tokens refreshed) but the error still appears later	Rotated tokens may not have been saved — look for "Session persist failed (token refresh)" in Relay's logs.
Refresh fails with invalid_grant / 400	The refresh token was consumed and not replaced (some servers issue single-use refresh tokens), or the refresh token itself expired.
Retrying after token refresh messages appear, followed by more Unknown token	The retried request still used a dead token — the refresh returned the same (stale) token. Combined with swallowed refresh errors, this is a strong race/stale-token signal.
Access token rejected (source: …) followed by the sign-out alert	The server confirmed the token is dead via a whoami probe — the session was invalidated remotely (e.g., password change, or sign-out-all-devices).

What to report

When filing an issue, include:

• The most recent 10 minutes worth of captured logs around the first failure (tokens are redacted in Transport logs, so they're safe to share — but skim for anything personal).
• How you logged in: password, or an OIDC/SSO provider (e.g., Matrix Authentication Service)?
• The homeserver type (Synapse? Dendrite? conduwuit?) and whether it enables refresh_tokens.
• Roughly how long the session survives before the error returns ("re-login fixes it temporarily" timing is useful).

Quick fixes worth trying

• Sign out fully and log back in (not just quit/reopen) — this replaces the refresh token, confirming whether the old one was dead.
• Check whether your homeserver admin recently changed token-lifetime settings or enabled token rotating.