Troubleshooting
Each symptom below is one Strado produces, with the cause and the fix. Where a subject has a page of its own, the fix links to it rather than repeating it.
macOS refuses to open the app
It should not. Builds since 0.1.35 are signed with a Developer ID certificate and notarized, so Gatekeeper lets them through on first launch. If yours is blocked, find out why before working around it:
spctl -a -vvv -t install /Applications/Strado.app
A signed copy reports source=Notarized Developer ID. Anything else means the
app was modified after signing or did not come from api.strado.io — download
it again from install. Builds before 0.1.35
were unsigned and did need xattr -cr; updating is the fix, not that command.
Something else was on the port
Starting a dev server clears its port first — it stops Strado's own servers on that port, then signals every other process listening there. So the usual surprise is the opposite of a failure: an unrelated server you were running got terminated.
If a start still fails, the log carries the reason. A conflict on a different port than the configured one is picked up from the error output and retried once, and both the eviction note and the crash output stay in the log.
See ports and run status and logs.
A session will not attach
First: closing a session tab kills that session. If a tab is gone, the process is gone — this is the one direction that does not survive. The exception is a session on a runner, where closing the tab detaches instead and the process keeps running.
If sessions vanish across a restart instead, check whether STRADO_INPROC_PTY
is set. In-process terminals die with the server; the daemon is what makes them
survive. See sessions.
The preview renders blank
Open the DevTools console first, with ⌘+⌥+I. A blank pane is almost always a page-level error, and the console says which — guessing past it wastes far more time than reading it.
If a preview_* tool reports no preview for the worktree, that is literal: the
bridge only sees Browser tabs open in that worktree. Screenshots additionally
need that Browser tab to be the visible hub tab, since a hidden view produces
no frames. See browser bridge.
A tab is missing entirely
Not a fault. The VS Code and Browser tabs are absent outside the desktop app, and absent on a runner worktree along with the Logs button, the diff, and the changes rail. They are hidden rather than shown broken. See the hub and remote worktrees.
Two instances fighting over state
Running electron . inside packages/desktop skips the npm scripts, so
STRADO_PROFILE is unset and you get the stable profile — the same state
directory and the same port as an installed Strado.
Use npm run desktop. See
environment and profiles.
A runner shows offline
Work down it in this order, on the box:
| Check | Command |
|---|---|
| Is it paired? | strado-runner status |
| Is the service up? | systemctl --user status strado-runner |
| Will it survive logout? | strado-runner status — it warns when lingering is off |
| What does it say? | strado-runner logs |
See runner updates for the full sequence, including re-pairing.
A remote terminal says command not found
The systemd user service captured your login shell's PATH when it was
installed. Install an agent CLI afterwards and that snapshot is stale.
strado-runner env
That re-captures it and restarts the service. See install a runner.
A dev server refuses to start at all
Two refusals happen before anything is spawned, so there is no crash output to read:
- The start command is empty.
- The repo has env profiles but its start command has no
{ENV_FILE}placeholder. See env profiles.
An agent's status never updates
Status is refused for any directory that is not inside a repo you registered. An agent started somewhere Strado does not manage reports nothing, by design.
The reporting also gives the server about a second and then gives up silently, so it never stalls your agent — which means a server that is down produces no update rather than an error. See agent status.