Troubleshooting
Find your symptom, see why it happens, and fix it. Plus how to send a Griddler Trace and where the logs are.
Where: Top bar→Doctor
Open the Doctor first. It catches most of what's below and puts the fix on the row.
A pane never turns green
- Codex pane. Codex has no finish signal. Its pane turns green after it goes quiet for a moment, marked went quiet — probably waiting on you.
- Claude Code pane, hooks off. The Doctor's Attention hooks row warns. Click Repair attention hooks, then start a new pane. Panes that were already open don't pick up the change.
- curl is missing. The curl row fails. The green signal needs curl; click ▶ Run on that row.
- Another Griddler is running. Hook listener :47831 says port in use by another Griddler. Quit the other copy and restart this one.
- It turned green and stayed green. Green clears when you press Enter in the pane, not when you click it. See Know when a pane needs you.
The Tavern button is missing
The 🍺 button only shows when you're signed in. Sign in, and it appears a few seconds later. The Doctor's Tavern / social row says whether it's set up. See Tavern.
Mail button is missing
The mail button (the inbox tray in the top bar) only shows when you're signed in, or when the older mail setup in Settings→claude-mail is found. It appears as soon as you sign in. If it doesn't, check which account you signed in with; see the next section. See Mail.
✅ Tasks and 😟 worries follow the same rule and also appear right after sign-in.
Signed in, but team features stay empty
Settings says Signed in as an address that isn't @riverlogic.com. Only @riverlogic.com accounts get team features. Click Sign out in Settings→Account, then Sign in with your River Logic account.
Sign-in keeps expiring
Find which sign-in it is. Each has its own Doctor row.
| Doctor row says | Fix |
|---|---|
| Service account: sign-in expired | Sign in again from Settings→Account. |
| Service account: saved sign-in unreadable | Sign in once more. On Linux this happens when the system keyring changes; after one more sign-in Griddler stays with that keyring. |
| Service account: service unreachable | Nothing. You're still signed in, and Griddler retries on its own. |
| Azure DevOps: sign-in expired (for example multi-factor authentication expired) | Click Set up…, then Connect Azure DevOps. |
| Profiles: logged out — panes on this profile will 401 | Click Log in… on that account in 🎭 Auth profiles. |
Going offline never signs you out. Settings shows (offline — will reconnect).
Agents in a pane don't have the team tools
The pane opened before you signed in. Open a new pane. See What your agents can do on the team.
Deploying an agent fails
The Agents panel shows the failed step and its log. The Doctor's Agent host row says whether Docker Desktop is ready on this machine. The rest is on Griddler Agent.
Codex doesn't show up
- Hidden on this machine. The Codex section of 🎭 Auth profiles says Hidden on this machine. Click Show.
- Not installed. The launcher lists Codex — not installed. In the Doctor, click ▶ Run on the Codex
CLI installed row, then run
codex login.
A pane closes as soon as it starts
The Doctor shows Panes are dying on launch with the agent's own error. The rows above it say why:
- CLI launches or Binary intact fails: the agent's install is broken. Close Griddler, then run the fix from the row in a terminal. Windows won't replace a program that's running.
- config.toml fails: Codex's settings file is corrupt and Codex won't start. The row names the file and the error; fix that line.
- Logged in (default) warns: log in with
claudeorcodex login.
An update never installs
Griddler downloads updates but only installs when you say so. Click Update in the top bar, or Restart & update in Settings. The portable Windows build and macOS don't update themselves; see Install and update.
Copy doesn't reach my own computer over Remote Desktop
The Doctor shows Clipboard (RDP): rdpclip.exe not running — copies will not reach your local machine. Click ▶ Run on that row.
Griddler is slow or panes draw wrong
- Check Leftovers in the Doctor. Click Clean up to end background processes Griddler left behind.
- Set Settings→Appearance→Terminal renderer to Auto — GPU when available. Use DOM (compatibility) only if text draws wrong. See Themes and fonts.
- Press Ctrl/⌘+Shift+R to restart Griddler cleanly. Your panes come back.
The Welcome page couldn't clone the archive
The message says your Azure DevOps sign-in has expired or is missing. Click Connect Azure DevOps in row 1, then Create again. See First run.
Meetings don't load on Today
- Sign in to see meetings. You're signed out. Sign in.
- Meetings are not set up for this hall yet. Meetings aren't connected for your team. Ask an admin.
- Not enrolled for meetings yet — ask an admin to add you to Griddler-Meetings. Ask an admin.
See Today.
Send a Griddler Trace
A Griddler Trace is a snapshot of what's wrong, for support. Type what's happening in What's going wrong?, then click Submit Griddler Trace in the Doctor or in Settings→Support. Quote the Trace ID it shows. It works signed out too.
A Trace holds:
- Griddler's version, your OS, and your note
- the names of your settings, not their values
- recent errors and every Doctor row
- the last two prerequisite install logs
- the last failed Deploy, Re-sync or Remove of a Griddler Agent, with its step log
- the end of Griddler's log
Keys, tokens, and secrets are removed, and your home folder shows as ~. Message bodies aren't included.
Support keeps a Trace for 30 days. 🩺 Copy Griddler Trace or Copy instead copies it to your clipboard
without sending.
Find the log files
Click Open log folder in the Doctor. The folder is ~/.griddler/logs/:
| File | Holds |
|---|---|
griddler.log | Today's log. |
griddler-YYYY-MM-DD.log | Earlier days, kept 30 days. |
setup-<time>.log | Each Set up all prerequisites or ▶ Run install. The newest 10 are kept. |
What Griddler sends
Griddler reports usage and health so problems can be spotted across the team. There's no switch to turn it off.
- Your plan usage percentages and reset times.
- An hourly health summary: version, OS, the Doctor's result, agent versions, pane counts, error counts with ids and paths blanked, and how often each feature was used.
- Crash reports: the error and where it happened.
- Game events.
It includes your machine name and your handle. It never includes what you typed, what agents wrote, or mail. Reports only leave while you're signed in; signed out, they wait on your machine.
Related
- Doctor
- Signed in or not
- Griddler Agent: its own deploy and connection problems.