Reference
Troubleshooting
Common Cyborg issues and how to fix them.
A machine won’t start, or its port is in use
The daemon listens on 127.0.0.1:6780 by default.
Fix: Another daemon may already be running on that port. Run cyborg daemon status to see it, then cyborg daemon stop, or choose another port with cyborg daemon start --port <port> (or PASEO_LISTEN). When you run from a source checkout, pnpm dev:cyborg uses port 6780 for the daemon and 5173 for the UI, while plain pnpm dev starts only the daemon, on port 6768.
An update did not take effect on a machine
The machine reports the new version but behaves like the old one.
Fix: A daemon that is already running ignores a start command unless you pass --replace. Use cyborg daemon update, or cyborg daemon start --replace. A systemd unit must use cyborg daemon start --replace --foreground. See the CLI reference.
cyborg behaves like an old version, or Settings says “Another cyborg runs first”
The terminal runs a different cyborg than the app’s: often a pnpm link --global or npm link of a source checkout, or an older install, earlier on your PATH.
Fix: Run cyborg doctor. Its binary row names the cyborg your shell runs and prints the command that removes it (for a pnpm link --global: pnpm rm --global @getpaseo/cli). Run that command, open a new terminal, and check Settings → System → Command line again. cyborg doctor --fix repairs only what the app owns (its command and PATH line) and never removes another install.
Links open the wrong copy of Cyborg
Sign-in or invite links open an old copy of the app (in Downloads or on a mounted disk image) instead of the one in Applications.
Fix: Open Settings → System → Diagnostics and click Run diagnostics. The Links row lists the other copies that can open cyborg:// links. Move the ones you don’t use to the Trash and keep the one in Applications.
Cannot find module / dependencies out of sync (source checkout)
Imports fail after merging or switching branches.
Fix: Run pnpm install to reinstall workspace dependencies, then restart the daemon.
Database migrations fail or hang
Fix: Run migrations with the supported command, pnpm db:migrate from a checkout, or docker compose run --rm migrate from deploy/ in a Docker install. Pending migrations are applied and applied ones are skipped, so it is safe to re-run. Migration files live in packages/server/src/server/cyborg/db/drizzle/. If a single file must be applied by hand, use psql "$DATABASE_URL" -f <file> and do not paste the connection string into shared logs. Only the relay’s shared PostgreSQL database needs migrations.
Postgres: “The server does not support SSL connections”
The relay negotiates TLS to any non-loopback database host by default, and a Postgres without TLS refuses it.
Fix: Append ?sslmode=disable to DATABASE_URL, or set PG_SSL_MODE=disable. For a managed database whose certificate you want verified, set PG_SSL_MODE=verify-full. See Docker.
docker compose up fails on port 6379
The bundled Valkey is published on host port 6379, and another Valkey or Redis is already listening there.
Fix: Stop the other server, or change the valkey port mapping in deploy/docker-compose.yml.
An agent never goes online / no response
You created an agent but it never streams output.
Fix: Check: 1) the provider (Claude Code, Codex, GitHub Copilot, OpenCode or Pi) is installed and signed in on that machine (cyborg provider:list and cyborg provider:sign-in), 2) the agent’s working directory exists, 3) the daemon’s logs for spawn errors. Agents run as processes on the machine’s own computer. A stuck session can be restarted in place with cyborg agent:reload.
An agent on a local model doesn’t answer
The agent runs on Local · machine name and stops with can't reach, is no longer on, Needs key or Needs OpenCode.
Fix: Check the machine’s Local models list (or cyborg machine:local-servers <workspace-id> <machine-id>): the server must say running, and OpenCode must be installed on that machine. No Local · machine name row in the model picker means local models are not turned on there (features.localOpenCode, see Turn on local models). Each message and its fix is in Run agents on local models.
Messages not syncing across machines
Messages appear locally but teammates on other machines don’t see them.
Fix: Check: 1) the machine is connected to the relay (cyborg daemon doctor shows the relay link and online state), 2) the relay’s database is reachable (DATABASE_URL on a self-hosted relay), 3) the relay logs for the relay_subscribed confirmation. Each machine only receives the workspaces it belongs to.
An agent won’t spawn (pi not found)
cyborg cybo:spawn fails to launch the agent on the machine.
Fix: agents on the Pi provider need the pi binary on the machine’s PATH. Install it from the machine’s Providers list, or with cyborg provider:install <workspace-id> pi --daemon <machine-id>, then cyborg provider:refresh <workspace-id> pi --daemon <machine-id>. Claude and Codex agents do not need pi.
The relay refuses to boot
The relay exits at startup complaining about the JWT secret.
Fix: CYBORG7_JWT_SECRET must be set to a strong value of at least 32 characters. The relay refuses to run on a public interface with a missing, short or public-default secret. Generate one with openssl rand -hex 32, or run tools/gen-selfhost-secrets.sh deploy/.env.
Asset upload (avatars, attachments) fails
Uploads error out on a self-hosted relay.
Fix: The default storage backend is S3 (ASSETS_BACKEND=s3): set S3_ASSETS_BUCKET, S3_ASSETS_REGION and the credentials on the relay (with Docker Compose, in deploy/.env; the relay service loads it, Compose 2.24 or newer), and check the relay logs for the presign step. To avoid S3, set ASSETS_BACKEND=fs (the relay’s own disk) or point ASSETS_S3_ENDPOINT at an S3-compatible server such as MinIO. See Configuration.