Skip to content

Troubleshooting

Ryan Stoffel edited this page Oct 29, 2026 · 1 revision

Troubleshooting

Run the doctor

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 doctor

It 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.

Logs and the data folder

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.

Connection errors

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

plxd attach exit codes

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.

The login service

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.

Providers

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 on Windows

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.

API keys

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"

Your Parallax account on Linux

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.

Install script messages

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.

Unsigned builds

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.

Update messages

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

Filing a bug

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.

Clone this wiki locally