Troubleshooting

If something isn't working, this page has the common cases. Start with the symptom that matches yours.

Quick checks before anything else

1. Look at the tray icon

Grey = offline (sign-in or network), green = online, animated = running. The icon tells you whether the problem is "can't connect" or "running but something's wrong with the work".

2. Open the log viewer

Settings → Logs → Open in-app log viewer. Most issues surface as a warn or error line with a clear message. Search for the word "error" first.

3. Try Resync

Tray menu → Settings → Resync now. Many drift issues (missing project, stale agent list, stale MDS env) get fixed by a full resync.

Common issues

An agent looks busy but the task is sitting in Review

Check whether the session state is Reviewing rather than working. A reviewing session reads a diff and produces a verdict; it writes nothing and emits far less output than a coding session, so it looks idle when it is not.

The Station has shown Reviewing as its own state since 1.3.0, and the Dashboard counts working and reviewing separately. Before that, both appeared as ordinary running work, which made this the most common reason to suspect a stuck Station.

What is normal here:

• A review runs alongside the coding session in the same project — it does not wait for the checkout, and it does not hold it. Two reviewers can run in one project at once.
• A review ends when the review ends, not when the task leaves the working column.

If it really is not progressing, see When an agent stalls.

Tray icon stays grey, can't sign in

You're seeing the sign-in screen but the OAuth flow won't complete, or the tray stays offline after sign-in.

Likely cause: the deep link from the browser back to Build Station isn't firing.

Fix:

• Make sure the browser is allowed to open external apps for your Meshly Build URL.
• macOS: try signing in from Safari rather than Chrome — Safari has better default behavior for custom URL schemes.
• Windows: check the Default apps settings under Settings → Apps → Default apps and search for meshly-station — make sure Build Station is registered for that protocol.

If the deep link fires but the tray still goes grey, check the log viewer for auth or keyring errors — sometimes the OS keychain refuses to store the token (e.g., locked keychain). Unlock the keychain or sign in again.

Task moves to In Progress but the agent never starts

The dashboard shows the task transitioning In Progress (because Build Station called start_task) but no live console output appears and no commit ever lands.

Likely cause #1: the claude CLI isn't found on PATH for GUI-launched apps.

macOS GUI apps don't inherit your shell PATH — Build Station has to find claude via standard install locations. If your install is non-standard:

• Set the MESHLY_CLAUDE_BIN environment variable to the absolute path of the claude binary (Settings → Advanced).
• Relaunch Build Station.

Likely cause #2: the project's working directory doesn't have the expected structure.

If the project expects to be a git repo but the working directory isn't, or if .mcp.json couldn't be written there, the spawn fails silently. Check the log viewer for process::manager errors.

Streaming console doesn't show output

Tray icon says "1 agent running" but the dashboard console view is blank.

Likely cause: WebSocket connection from Build Station to the backend's console-feed endpoint is being blocked.

Fix:

• Check the log viewer for console_feed errors.
• If you're behind a corporate firewall or proxy, the /ws/console/feed endpoint may be filtered. Whitelist your Meshly Build domain over WebSockets (port 443 over wss://).
• As a workaround, the agent is still running and logging locally. Open the per-session log file (logs/sessions/<task-id>.log) to see the same content offline.

Agent runs but task stays In Progress forever

The agent is doing work, the console shows progress, but the task on the dashboard never moves to Review.

Likely cause: the agent didn't call complete_task itself.

After 5 minutes of console silence, Build Station nudges the agent. Often that's enough — the work was done, the agent just forgot the final step. See When an agent stalls for the full recovery flow.

If after 10 minutes total nothing has moved, Build Station blocks the task on the server and kills the session. You can then move it back to To Do on the dashboard to retry.

"Agent X already has a task In Progress" errors

The dispatcher tries to start a task and the backend rejects with an "agent has 1 task In Progress" message.

Likely cause: another session for that same agent identity is already running — possibly on a different Build Station you have signed in.

Fix:

• Each agent identity can only work on one task at a time across all Build Stations under your account. If you have two Stations running with the same agent, one will lose this race.
• Either disable the agent on one Station, or split work across distinct agents.

Agent says the MCP server "needs OAuth" or Meshly tools have disappeared

A session reports that meshly-build (or an mds-* server) is not authorized and asks for an interactive sign-in, even though the agent's credentials are fine and everything worked before.

Likely cause: the Claude Code CLI keeps its own cache of servers whose last connection attempt failed, and once a server is in that cache, Claude Code stops trying to connect to it — it will not run the credential helper again to check whether the problem is still there. One bad connection attempt (for example right after Build Station moves or updates) is enough to trip this, and every later session on the machine inherits it, in every project, until the cache entry is cleared.

Build Station clears this cache entry itself whenever it writes a fresh MCP config for a server, so a Resync (Tray menu → Settings → Resync now) is usually enough to recover, and normal use should not hit this at all.

If tools are still missing after a Resync:

• Quit any running Claude Code sessions for the affected project first — a session already connected keeps its own in-memory state regardless of the cache file.
• macOS/Linux: echo '{}' > ~/.claude/mcp-needs-auth-cache.json
• Windows: echo {} > %USERPROFILE%\.claude\mcp-needs-auth-cache.json
• Start a new session. The credential helper runs again on the next connection attempt.

Resync says "Failed to fetch MDS envs: Deserialization error"

You see this in the log viewer after a resync.

Likely cause: your Build Station is older than the backend's MDS API. The response shape changed in a backend update and the older client doesn't know how to parse it.

Fix: update Build Station. Settings → Updates → Check now. If you're already on the latest version, file feedback — the backend may have changed in an unexpected way.

Working directory keeps "unset" even after picking a folder

You click Set working directory, pick a folder, but the field clears or shows an error.

Likely cause: the path you picked isn't actually a directory (e.g., a symlink to a missing target) or Build Station doesn't have permission to read it.

Fix:

• Verify in Finder/Explorer that the folder really exists and you can open it normally.
• On macOS, if the folder is in a protected location (e.g., another user's home), grant Build Station Files and Folders permissions in System Settings → Privacy & Security.

Tray icon stuck animated, but no agents are actually running

The icon says "running" but the dashboard shows no In Progress tasks for this Station's agents.

Likely cause: a stale process state in Build Station's in-memory tracking — typically after a tmux window was killed externally and the dispatcher didn't see the death.

Fix:

• Tray menu → Settings → Stop all agent sessions. Forces a cleanup of stale state.
• If the icon is still animated after that, quit Build Station (tray → Quit) and relaunch.

Notifications never appear

Even with notification toggles on in Settings, no desktop notifications show.

Likely cause: OS-level permission for Build Station to send notifications is off.

Fix:

• macOS: System Settings → Notifications → Meshly Build Station → ensure Allow notifications is on.
• Windows: Settings → System → Notifications → Meshly Build Station enabled.
• Test from Settings → Notifications → Test button next to any event.

Build Station won't update past version X.Y

The updater says a new version is available but installing it fails or reverts.

Likely cause: signature verification failing, or a permission issue with the install path.

Fix:

• macOS: re-download the .dmg manually from the release page and install over the existing app.
• Windows: same — download the .msi and run it. Re-installs over the existing version.
• Check the log viewer's updater module for the specific error.

Sign-in token expired and won't refresh

You get a "session expired" notification and the tray goes grey unexpectedly.

Likely cause: the refresh token expired (longer-lived than access tokens but not forever) or the backend rotated keys.

Fix: tray menu → Sign in again. You'll go through the OAuth flow once more.

Still stuck?

If none of the above fixes your issue:

1. Capture logs at debug level

Settings → Logs → set level to debug → reproduce the issue → note the timestamp range.

2. Open the session logs folder

Find the per-task log for the broken task (logs/sessions/<task-id>.log).

3. File a report

Contact your Meshly account contact with: Build Station version, OS, the timestamp range of the issue, and the relevant log slices.

Most issues we see fall into one of the categories above. The newer the install and the more recent the resync, the less likely you are to hit an edge case.