Most problems announce themselves in the header line, next to the status LED. Here's what the common ones mean and the shortest way out of each.
Your token expired or was revoked, or the password changed. Press A to reopen the connect form as "Reconnect to GoCD", enter the new credential, and you're back in, no quitting, no hand-editing the config file.
Running with env vars? Remember GOCD_TOKEN / GOCD_PASSWORD override the file, so a stale exported value will keep producing 401s even after you reconnect.
The LED turns red and the header shows the error, but nothing goes blank: the last loaded dashboard stays fully browsable from the disk cache, so you can still navigate the tree and read cached history.
You don't need to do anything to recover. The app re-polls every poll_interval_secs (30 seconds by default), so as soon as the VPN or network comes back, the next poll succeeds and the view refreshes on its own. Press r if you want to retry immediately.
Your GoCD server uses a self-signed or internal-CA certificate that your machine does not trust. The fix worth doing first is adding that CA to your operating system's trust store, which keeps verification on and fixes every other tool on the machine at the same time. Many organisations run TLS inspection and already ship this root on managed laptops, so check there before anything else.
If you cannot do that, set insecure_skip_verify = true in ~/.config/lazygocd/config.toml, or launch with GOCD_INSECURE=1. There is no prompt for this in the connect form: verification is always on unless you edit the config yourself.
The detail pane names the reason, and the message row carries the full text. The check works unauthenticated for public repos (rate-limited); a private repo needs credentials, so press @ and paste a token with read access, or export GITHUB_TOKEN before launching.
needs SSO authorization. The organisation enforces SAML SSO and this token has no grant for it. A classic personal access token you created by hand is not authorized until you go to Settings > Developer settings > Personal access tokens > Configure SSO and authorize that org. The GitHub CLI's own token usually already carries the grant, because it was minted through a browser login that passed the SAML flow, so clearing github_token from the config is often the faster fix.
token invalid. A 401. The token is revoked, mistyped, or expired.
Since v0.10.6 a token rejected with 401 or 403 is retried once against gh auth token, and the status line says so when that is what worked. So a stale value in the config no longer shadows a working GitHub CLI session.
No comparison shown at all? Since v0.7.0 a deploy pipeline triggered by an upstream build is traced through its pipeline dependency, and the commit is shown with a via <pipeline> #<counter> line. If nothing appears, the run has neither a Git material nor a pipeline dependency leading to one within four hops.
The very first load has no cache to lean on and has to pull the whole dashboard once. Gzip keeps that reasonable (2–4 seconds on a large instance), and the client allows up to 45 seconds for slow links. Every launch after that paints instantly from the disk cache while refreshing in the background.
It isn't; it starts fully collapsed on purpose, since hundreds of expanded groups would be unusable. Move onto a group and press l or enter to expand it, or press / and type a few characters to fuzzy-filter across everything at once.
| Path | Contents | Safe to delete? |
|---|---|---|
~/.config/lazygocd/config.toml | Server URL, credential, TLS setting, poll interval, optional GitHub token (mode 0600) | Yes; the connect form reappears on next launch |
~/.config/lazygocd/dashboard_cache.json | Last successful dashboard load | Yes; the next launch just waits for the network once |
~/.config/lazygocd/favorites.json | Starred pipeline names | Yes; you lose your stars |
Deleting all three is a full reset. Env vars (GOCD_URL, GOCD_TOKEN, ...) still override whatever the files say; see the quickstart.