When a connection breaks
A connection can go bad in exactly two ways — its token stopped working, or it can't be reached at all — and Deckgauge tells the two apart so you're not guessing which one you're looking at.
ada-systems/checkout expired
FieldValue
Paste new token•••••••• [Save]
A source card expanded on an expired token, showing the inline reconnect box.
What the health badge means
| State | What it means |
|---|---|
| Valid | The connection's own test call succeeded |
| Expired | The test call came back 401/403 — the token itself is bad |
| Unreachable | Anything else failed (DNS, timeout, 5xx) — treated as transient, not a token problem |
That distinction matters for scheduling too: an unreachable source is still attempted on the next sync (it might only be a blip), while an expired source is skipped on Sync Now so one bad token doesn't hold up every other source on the board.
How to reconnect
- Watch for the ⚠ Token expired button on the board's sync controls, or the health badge on a source card in the Sources tab.
- Clicking it jumps straight to the broken source via
?fix=<provider>:<instanceId>in the URL — the exact card opens automatically with its reconnect box already showing. - Paste a new token and save. The new token is validated before it's stored — a bad paste never silently overwrites a working connection with a broken one.
The two banners
Two different problems get two different banners, so the fix on screen always matches the actual cause:
- Reconnect banner ("This connection's token is expired or invalid…") — shown for GitHub, GitLab, and Azure DevOps whenever a probe or a live picker call comes back unauthorized. It carries the same token-creation walkthrough as the original connect form, so you're not hunting for the right scopes a second time.
- Host-fix banner (Jira only) — shown when the failure looks like Atlassian's vanity/display domain rather than a bad token. Its Use this URL button repoints the connection at the canonical
*.atlassian.nethost and retests automatically — see Connecting Jira for why this happens.
Per-provider, what to actually do
| Provider | If expired |
|---|---|
| Jira | Check for the host-fix banner first — most Jira "expired" reports are really the vanity-domain trap. If the host is already correct, generate a new API token and paste it. |
| GitHub | Reissue the PAT with the same scopes, and re-authorize it for any SSO-protected org it needs to read. |
| GitLab | Reissue the access token with read_api/read_repository/read_user. |
| Azure DevOps | Reissue the PAT with the Code, Work Items, and Project & Team read scopes. |
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| Badge says Expired right after pasting a new token | The new token itself failed validation and wasn't saved | Re-check the token was copied in full, with the right scopes |
| Badge flickers between Valid and Unreachable | Transient network issue with the provider, not the token | No action needed — it clears on the next successful probe |
| Jira keeps 401ing after pasting a fresh token | Still pointed at the vanity/display domain | Use the host-fix banner, or manually switch the URL to *.atlassian.net |
Related
- Connecting Jira — the vanity-domain trap in full.
- When your data refreshes — how an expired source affects scheduled sync.
Last updated