Troubleshooting

Each entry starts with what you see, then the fix. Messages in quotes are the exact text the app shows. The app still calls itself Pix, so its messages do too.

Where to look first

• Settings → Agents shows each agent’s status and sign-in.
• Settings → Devices shows paired devices and the status of each remote route.
• The daemon log is logs/daemon.log inside the data directory: ~/.pix/logs/daemon.log on macOS, ~/.local/share/pix/logs/daemon.log on Linux. On macOS the service also writes to ~/Library/Logs/PIX.

An agent is not signed in or not installed

Weaver uses each agent’s own login. It does not have a separate account.

In Settings → Agents, the agent shows “Not connected”. The agent has no usable credential. Click Connect and pick a sign-in method. Depending on the agent, sign-in runs in a terminal inside Weaver or opens a browser window. You can also sign in with the agent’s own CLI on the daemon’s machine; Weaver picks up that login.

The agent shows “CLI required”. The agent’s runtime is missing. Click Set up and Weaver installs it, then checks again.

A chat shows a “login required” card. The agent rejected the turn because its credential is missing or expired. Use the action on the card to sign in, then send again. The card changes to “logged in” when it succeeds.

Cursor says “a Cursor dashboard API key is required”. Cursor does not reuse the Cursor app’s login. Create an API key in the Cursor dashboard, then open Settings → Agents → Cursor, click Connect, and choose Configure API key. Weaver stores the key in an owner-only file.

The agent works in your terminal but not in Weaver. The daemon runs as a background service and does not inherit your shell’s environment variables. If the agent depends on one (an API key or a gateway URL), add it under Settings → Agents → Environment. Each agent’s runtime receives those variables at launch.

The app cannot reach the daemon

The start screen says “This workspace didn’t answer.” or a running turn shows “Reconnecting”. The client cannot reach the daemon and keeps retrying on its own. On the same Mac this usually means the daemon is starting, restarting, or stopped. From another device, the daemon’s machine may be asleep or offline; see the relay. The start screen also lets you pick another machine.

The start screen says “We hit a locked door.” Weaver could not open this machine with its saved connection. Check the saved connection in Settings → Devices. If the device was revoked on the daemon’s machine, pair it again.

A dialog says “Pix could not start its daemon”. Another Weaver daemon, often a development build, still holds the data directory or port. Quit any other Pix app or development daemon, then launch Pix again.

An error says “Another daemon owns the Pix data directory” or “A previous Pix daemon still owns the Pix data directory”. Same cause. Only one daemon can own a data directory at a time.

On macOS the daemon runs as the LaunchAgent com.ritesh.pix.daemon. On Linux it runs as the user service pix-daemon.service. Closing the window can leave the service running so your sessions continue.

Do not ask an agent inside Weaver to restart the daemon. The daemon hosts that agent’s turn, and Weaver refuses those commands for Claude Code, Pi, Copilot, and OpenCode. Updates go through Weaver‘s own update action, which finishes active work first.

Pairing fails

“Pix could not create a pairing code on this network.” The Mac has no address another device can reach: no LAN address, no relay connection, and no Tailscale. Connect the Mac to a network, then check Settings → Devices → Remote access.

“Camera access is required to scan the pairing code.” Allow camera access for Pix in the phone’s Settings, then scan again.

“That isn’t a Pix pairing code.” You scanned some other QR code. Scan the one in Settings → Devices → Connect mobile on your Mac.

“pairing code invalid or expired”. The code was already used, or someone showed a new code that replaced it. Click New QR code and scan again.

“could not reach the daemon” or “pairing timed out”. The phone could not reach any route in the code within 15 seconds. Put the phone on the same Wi-Fi as the Mac, or check that Remote access shows the relay as connected, then try again.

“That invitation has expired. Create a new one on the other device.” Mac invitations last five minutes. Create a new one on the Mac you want to control.

“The invited Mac was not reachable on any shared route.” The other Mac is asleep, offline, or not running Weaver, or neither LAN, relay, nor Tailscale connects the two. Wake it, check its Remote access status, and create a fresh invitation.

“macOS secure storage is unavailable, so pairing another Mac is disabled.” or “Pairing another Mac requires encrypted connection storage.” Weaver stores the other machine’s credential in the system’s secure storage (the Keychain on macOS, the Secret Service keyring on Linux) and will not store it in plain text. Unlock the keychain or keyring, then quit and reopen Pix.

“Restart the Mac app to enable saved connections.” Quit and reopen the desktop app.

“Connect to This Mac to pair another Mac.” You are viewing a remote machine. Switch to This Mac in Settings → Devices first.

The relay is not connected

Check Settings → Devices → Remote access. Each route shows its status.

“Connecting to the Pix relay…” and it does not change. The daemon cannot hold its outbound connection to the relay. The relay needs outbound secure WebSocket (WSS) traffic to Cloudflare. Check for a firewall, proxy, or captive portal on the Mac’s network. The daemon keeps retrying with backoff; a dropped connection is detected within about 20 seconds.

“Remote access is not configured for this Pix build.” Development and source builds have no relay address. Use LAN or Tailscale, or install a release build.

Your phone cannot connect away from home. The Mac must be awake, online, and running Weaver. The relay reaches your Mac; it does not keep a copy of your work.

Downloads, video previews, or the simulator stream fail on a remote device. These do not go through the relay. They work only over LAN or Tailscale.

“Tailscale is not running on this host.” Start Tailscale on the daemon’s machine and sign in. Weaver looks for the tailscale command in /opt/homebrew/bin, /usr/local/bin, inside /Applications/Tailscale.app, and on your PATH. The device you connect from must be on the same tailnet.

Linux: the service or keyring fails

Weaver on Linux needs a systemd user session and an unlocked Secret Service keyring. It is qualified on Ubuntu 24.04 Desktop, Fedora 43 desktops, and x64 Arch-based desktops including CachyOS. WSL, headless servers, and minimal containers are not qualified.

“Pix could not … its Linux user service … Run Pix in a systemd user session”. Your session has no systemd user manager. Log in to a normal desktop session. Inspect the service with:

systemctl --user status pix-daemon.service --no-pager
journalctl --user -u pix-daemon.service --since '15 minutes ago' --no-pager

“Pix user service failed; inspect journalctl —user -u pix-daemon.service”. The daemon exited. Read the journal output above for the reason.

“Run Pix as your normal Linux user, not root”. Start Pix from your own account. Never run it with sudo or --no-sandbox.

“The Pix user service is changing state; wait for it to settle and reopen Pix”. Wait a few seconds and open Pix again.

A keyring prompt appears. Allow the desktop keyring to unlock. Do not switch to plain-text credential storage.

“Existing Pix data was found at /home/you/.pix. Set PIX_DATA_DIR to that directory or explicitly migrate it …” An older install left data in ~/.pix. Weaver will not create a second copy. Point PIX_DATA_DIR at ~/.pix, or move that data to ~/.local/share/pix.

apt reports a downgrade, or Weaver reports incompatible data. Stop. Do not force the install. Get the matching package for your channel.

Removing the package keeps your data in ~/.local/share/pix, ~/.local/share/pix-runtime, ~/.local/state/pix, and ~/.config/Pix. Do not delete these to work around a startup failure.

A turn will not stop

Click stop. If the agent does not stop, Weaver shows a banner with Force stop. The banner says what force stop will affect. For some agents it restarts the agent’s runtime, which also interrupts that agent’s other running turns; for some, work already running on the provider’s side cannot be stopped.

Report a problem

Type /feedback in any session. The report includes the session transcript and raw log, so check them first. See Analytics and privacy for exactly what it sends.