Repository navigation
Troubleshooting
plx-connect doctor checks Parallax on the computer you run it on, asking the running plxd itself. It needs Node.js 20 or newer.
npx plx-connect doctorIt checks:
| Check | What it looks at |
|---|---|
| plxd | Whether plxd is found, and its version |
| Running | Whether plxd is running and answers |
| Restart | Whether the running plxd's binary was replaced since it started |
| Up to date | Whether plxd is the newest release of its channel |
| Project store | Whether plxd can use its store, and how long writes wait |
| Each provider | Whether it's installed and signed in |
| Connect | When Parallax Connect is on, whether Tailscale runs and plxd listens |
| git | Whether git is on PATH
|
| Disk | Free space. Under 10 GiB is a warning, under 2 GiB a failure. |
| plxd log | Errors and warnings in the last 24 hours |
In a terminal, it offers a fix for each failed check it can fix, such as starting plxd or signing in to a provider. Then it offers to open Claude Code or Codex with a prompt that asks what went wrong, looks into it, and helps you file an issue. --agent claude or --agent codex picks one without asking, and --model sets its model. The prompt and a context file go in doctor/<time> in plxd's data folder, or in the temp folder when there's no data folder, so you can paste them into any agent.
plxd writes its log to logs/plxd.log in its data folder. To open the folder, go to Settings > Storage and choose Show in Finder, Show in Explorer, or Open folder next to Logs. Installing says where the data folder is.
| In the data folder | What it is |
|---|---|
logs/plxd.log |
plxd's log |
plxd.sqlite3 |
Threads, Projects, and their history |
worktrees/ |
Threads' git worktrees |
plxd.lock |
Held while a plxd serve runs |
tools/ |
CLIs and SDKs plxd installs for itself, such as gh and the Claude Agent SDK |
plxd serve logs at info by default. --log-level, or the PLXD_LOG variable, sets off, error, warn, info, debug, trace, or a list such as plxd=debug,warn.
When the app can't reach plxd on a computer, the computer shows as failed with one of these messages.
| Message | What to do |
|---|---|
| plxd couldn't be reached or started | plxd didn't start or didn't answer within 10 seconds. Read the end of logs/plxd.log. |
| plxd isn't installed | The app couldn't find plxd. |
| plxd attach rejected its arguments. Update plxd. | The computer's plxd doesn't accept what this app passes it. Update plxd there. |
| A handshake error ending in Update plxd. or Update the app. | The app and plxd speak different protocol versions. Update the one the message names. |
Parallax couldn't find plxd on <host>... |
For an SSH host, Install plxd in Settings > Connections installs it in ~/.parallax-plxd
|
<host>'s host key isn't trusted yet. |
Run ssh <host> once in a terminal to accept it |
<host>'s host key has changed. |
If you expected that, remove the old key from known_hosts, then run ssh <host> once |
ssh couldn't log in to <host> without a prompt. |
Press Sign in for a password, or run ssh-add for a key with a passphrase. On Windows, start the ssh-agent service first. |
Couldn't find <host>. Check its name, or your ssh config. |
Fix the host's name or your ssh config |
Couldn't reach <host>. Check that it's on and accepts ssh. |
ssh itself failed. Check the computer and its ssh server. |
Couldn't reach <computer> on this network. |
A paired computer didn't answer. Check that it's on, on the same network, and that Same network is on there. |
<computer> doesn't know this computer anymore. |
Remove it, then pair again with a new code |
Couldn't reach <device> over Tailscale. |
Check that the device is on and that Parallax Connect is on there |
<device> closed the connection. |
Check that it's signed in to your Tailscale account |
The app reaches plxd by running plxd attach, locally or over ssh. attach starts plxd when it isn't running and prints its own errors to stderr as plxd attach: .... When the plxd it started stops, the error quotes the last line that plxd logged.
| Code | Meaning |
|---|---|
| 0 | The connection ended normally |
| 1 | An I/O error after connecting |
| 2 | A usage error |
| 4 | Never reached plxd: it couldn't be started, the plxd that attach started stopped, or the 10-second timeout passed |
| 127 | From the remote shell: plxd wasn't found |
| 255 | From ssh: ssh itself failed |
plxd serve exits 3 when another serve already runs for the same data folder, and attach keeps trying to connect to that one. Why: 0009 and 0010.
With Parallax Connect on, plxd runs as a login service that restarts it after any exit. plxd service status reports whether the service is installed, loaded, and running. Run it as parallax service status if the parallax command is installed.
| OS | Service | Where |
|---|---|---|
| macOS | LaunchAgent io.github.ryan-stoffel.parallax.plxd
|
~/Library/LaunchAgents/io.github.ryan-stoffel.parallax.plxd.plist |
| Linux | systemd user unit io.github.ryan-stoffel.parallax.plxd.service
|
~/.config/systemd/user/ |
| Windows | Scheduled task io.github.ryan-stoffel.parallax.plxd, run at logon and every 5 minutes |
Task Scheduler |
On Linux, systemctl --user status io.github.ryan-stoffel.parallax.plxd shows the unit. The service runs ~/.parallax-plxd/plxd. plxd service uninstall stops and removes it.
Settings > Providers shows each provider's state on the chosen computer. Refresh checks the CLIs again.
| State | What to do |
|---|---|
| Not installed | Press Install where it's offered, or install the CLI yourself and press Refresh |
| Not authenticated | Press Sign in. It runs the CLI's own sign-in in a terminal under it. Cursor signs in through your browser instead. |
| Node.js 22.16 or newer is required | Claude Code runs through the Claude Agent SDK, which needs Node.js. Install Node.js 22.16 or newer on that computer. |
| Node.js 22.13 or newer is required | The same, for the Cursor SDK |
npm is required to install the <SDK>
|
Install npm on that computer |
| Installing the Claude Agent SDK… | plxd installs the SDK with npm the first time it's needed. Wait for it. |
Couldn't install the <SDK>: ... |
The npm install failed for the reason shown. Fix it, then start a thread, which tries the install again. |
A Cursor sign-in waits with "Approve the sign-in in your browser." until you approve it there or press Cancel.
Claude Code has no sandbox on native Windows. Claude Code threads run there, but a Claude run that needs Claude Code's sandbox is refused with "Claude Code has no sandbox on native Windows, so run plxd in WSL2 and add that as the host for workers". Sandboxed runs work on macOS and Linux. Why: 0023.
plxd stores API keys in the OS's key store.
| OS | Store | When it fails |
|---|---|---|
| macOS | The login Keychain | "the keychain is locked or access was denied" |
| Linux | The Secret Service | "no unlocked Secret Service: install one, such as gnome-keyring or KeePassXC, and unlock it, or run plxd serve in a logged-in desktop session" |
| Windows | None yet | "this host can't store API keys yet: plxd has no Secret Service support on this OS" |
The app keeps your Parallax account signed in by encrypting it with the OS keyring. On Linux without a keyring, the sign-in lasts until the app quits.
| Message | What to do |
|---|---|
| Parallax needs a Mac with Apple silicon. | There is no build for Intel Macs |
No Parallax build for <OS> <arch>. |
Parallax has no build for this computer |
No nightly found for <file> at https://github.com/ryan-stoffel/parallax/releases. |
The script looks at the 20 newest releases and found none with a build for this computer. Download one from the releases page. |
| Quit Parallax, then run this again. | The macOS script won't replace the app while it runs |
install-tui.sh prints the first two too. Its other messages are on Terminal.
Only the macOS build is signed. Windows and Linux builds are unsigned.
- macOS: the dmg is notarized after the release is published, and the notarization isn't stapled to it, so Gatekeeper checks it online on first open. A dmg downloaded before notarization finishes may get a Gatekeeper prompt.
- Windows: Smart App Control blocks unsigned installers, so the installer won't run on a computer where it's on. Why: 0029.
The Update button's card shows why an update didn't happen. Release Channels and Updates explains how updates work.
| Message | Meaning |
|---|---|
| Can't reach GitHub to check for updates. | The check didn't reach github.com |
| GitHub is limiting update checks. Parallax will try again. | GitHub rate-limited the check |
| The newest release has no update for this computer. | The newest release doesn't have this OS's build yet |
| There's no release on this channel yet. | No release of this build's channel was found |
| The update's signature doesn't match this app's, so it can't be installed. | The download isn't signed like the installed app |
| Updates work only in the AppImage. | This Linux install, such as the AUR package, doesn't update itself |
| Update failed: ... | Any other error, with its first line |
Search the existing issues first, then open a bug report. The form asks for:
- What happened and what you expected
- Steps to reproduce, starting from opening Parallax
- Screenshots or a recording
- The Parallax version, from Settings > General > About > Version
- The OS of the computer that showed the bug, and of the computer running the agent if it's a different one
- The agent and how it's signed in
- Log lines, if you have them
Redact keys, tokens, and home folder paths from anything you paste. Report security problems as SECURITY.md describes, not in an issue. Ask questions in Q&A.
npx plx-connect doctor can also file the report for you through Claude Code or Codex. See Run the doctor.
Start
Using Parallax
Your computers
Maintenance
Contributing