# Troubleshooting Fixes for the problems people hit most often, using the messages Patterm shows. For anything on a server, start with the service log: ```sh systemctl --user status patterm.service journalctl --user -u patterm.service -n 100 --no-pager ``` ## Install and update ### The installer says the service is running ```txt the background service is running; rerun with --update to replace and restart it ``` Rerun the installer with `--update`. See [Linux server](https://patterm.com/docs/linux-server.md#update). ### The installer refuses to go back a version The message says your installed version is newer and its databases may not open in an older one. An older Patterm can fail to open databases a newer one migrated. Go back only to restore a matching backup, then pass `--allow-downgrade`. See [Linux server](https://patterm.com/docs/linux-server.md#backups-before-migrations). ### Patterm refuses to open a database Patterm refuses to open a database that a newer version has migrated, and names the migrations it does not know. Run the newer version again. To go back, restore the databases from `backups/pre-migration-*` in the data directory and install the matching older version. ## The service ### Patterm is already using the data directory ```txt Patterm is already using , or its runtime lock is unavailable ``` Another Patterm already has that data directory. Two Patterms cannot share one, so stop the other one first. Check for a running desktop app, a second service, or a service you started by hand. If you meant to run both, give each its own data directory and pair them as hosts. See [Multiple hosts](https://patterm.com/docs/multiple-hosts.md). The installer's access options give a similar message, "Patterm is using this data directory". Stop `patterm.service` first, or change the setting in **Settings › Remote access**. ### The service keeps restarting If the terminal engine exits, the log shows `Terminal sidecar exited; stopping for service recovery`, and systemd starts the service again. Your agents are not stopped. If it keeps happening, the journal has the reason. The service gives up after five failed starts in a minute. If the log shows `Terminal sidecar is unavailable` on startup, the terminal engine could not start, and the service stops. The lines above it in the journal say why. ### The port is in use If another program holds port 8787, the service fails to start and the journal shows an address-in-use error. Free the port, or set `PATTERM_PORT` in `~/.config/patterm/patterm.env` to another one and restart the service. A `PATTERM_PUBLIC_ORIGIN` on `localhost` must use the same port. ### The service stops when I log out, or after a reboot User services stop when your last session ends, unless lingering is on. Start at boot and keep running after logout: ```sh systemctl --user enable patterm.service sudo loginctl enable-linger "$USER" ``` ### My agents vanished after a reboot A reboot ends every process. Patterm does not resume agents on its own. Open the project's history and resume each conversation. See [Linux server](https://patterm.com/docs/linux-server.md#what-survives-a-restart). ### Commands fail while Patterm restarts ```txt Patterm disconnected before responding. The command may have run and was not retried. ``` An agent sees this when one of its tool calls hits Patterm while it restarts. Patterm never retries a command it could not confirm. Check what happened, then run it again if needed. ## Agents ### An agent does not appear in the launch menu Under **Settings › Harnesses**, a CLI Patterm cannot find shows **Not discovered**. Launching it fails with `harness not available`. Patterm looks for `claude`, `codex` and `opencode` on `PATH`. On a server, that is the `PATH` in `~/.config/patterm/patterm.env`, plus what your shell adds when it starts. Install the CLI where the service's account can run it, then check `PATH` in `patterm.env` and restart the service. Agents keep running through a restart. ### An agent is signed out Each CLI keeps its own login, on the machine that runs the agent. On a server, sign in there, in a Patterm terminal or over SSH, under the same account as the service. ### OpenCode says the server version does not match ```txt OpenCode server version mismatch ``` The shared OpenCode server is older than the CLI. Patterm offers to restart it and launch again. The restart interrupts running OpenCode turns, so it only happens when you click it. ### MCP server does not connect Open **Settings › MCP servers** and choose **Test** on the server. - **Not signed in** means a remote server needs a sign-in. Choose **Sign in**. If the browser cannot reach the address it is sent back to, paste that page's full address into the box and choose **Submit**. - A **Local command** server fails to start if its command is not on `PATH` for the service. Install it on the machine that runs the agent. - A running agent keeps the servers it launched with. Restart the agent, or use `/restart` in an Integrated conversation. - A server you gave to one harness is not available to the others. Check **Give to**. - Codex uses its own saved login for a server name in place of Patterm's. If Codex reports a refresh error for a server that works in Patterm, Patterm's notification gives the `codex mcp logout` command that removes the saved login. Then restart the agent. See [Your MCP servers](https://patterm.com/docs/mcp-servers.md). ## Browser access ### Request origin is not allowed ```txt Request origin is not allowed ``` Patterm checks the address a browser used. Open it at the exact address shown in **Settings › Remote access**: `http://localhost:8787` on the server itself, or the `https://` name Tailscale gave it. Any other name is refused, such as the machine's IP address on a Tailscale or local setup. A request that comes through Tailscale Funnel is always refused. With **Only me** on, requests that Tailscale says come from another login are refused too. ### I can't reach the server from another device - Check **Open from** in **Settings › Remote access**. **This machine** accepts the server's own browser only. - For **Tailscale**, check that both devices are connected to the same tailnet and that your tailnet policy allows your device to reach the server's port 443. - Patterm shows a warning and falls back to **This machine** when it cannot honour the setting. The warnings are `Network access is off because no password is set.`, `Network access is off because this machine no longer has the address
.`, and `Tailscale access is off:` followed by the reason. ### Tailscale setup fails | Message | What to do | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `Tailscale is not connected. Run tailscale up first.` | Connect Tailscale on the server. | | `Tailscale Funnel is on for this machine. Turn it off before serving Patterm.` | Turn Funnel off. Patterm never serves through Funnel. | | `Tailscale already serves something else at https:///. Patterm will not replace it` | Run `tailscale serve status` and move or remove the other route. | | Tailscale asks for administrator permission when you run `--tailscale-serve` | Grant your account operator access once with `sudo tailscale set --operator="$USER"`. Do not run Patterm with `sudo`. | If Tailscale asks you to enable HTTPS for your tailnet, follow the link it prints. ### The sign-in page says Wrong password ```txt Too many wrong passwords. Try again in a minute. ``` Wait a minute and try again. If you forgot the password, stop the service, delete `server-access.json` in the data directory, and start it again. That file also holds the Remote access choice, so set **Open from** again afterwards. ### The page says Disconnected **Disconnected. Agents continue running. Reconnecting…** means the browser lost its connection. It retries by itself. If the server is not running, start it, then refresh. See [Browser and phone access](https://patterm.com/docs/browser-and-phone.md#when-the-connection-drops). ### The terminal won't take my typing **Viewing shared terminal** means another browser controls it. Choose **Take control**. ### Push notifications won't turn on - Installing and push need the HTTPS address, except on `localhost`. - If the message says "The service worker is not running", reload the installed app and try again. - Desktop and push notifications are sent only while no Patterm window is focused, and only above your **Minimum urgency**. Use **Send test notification** to check. ## Multiple hosts | Message | What to do | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `Pairing is off because this server accepts any tailnet user.` | Set a password in **Settings › Remote access**, or set `PATTERM_OWNER_LOGIN`, and restart. | | `The pairing code is incorrect.` | Check the code. | | `No pairing code is active on this host.` | Choose **Show pairing code** for a new one. Codes last ten minutes and work once. | | `Only a Patterm server can accept pairing.` | Show the code on the server and pair from the desktop app. | | `... uses an incompatible Patterm version. Update both hosts, then pair again.` | Update both. | | `A paired host is already called .` | Rename one host. Names are lowercase letters, digits and hyphens. | If a host shows **Offline**, messages for its agents wait and are delivered when it reconnects. See [Multiple hosts](https://patterm.com/docs/multiple-hosts.md). ## History and files ### A history source says Missing The folder or file no longer exists. Turn the source off, or add the right path with **Add source** in **Settings › Conversation history**. **Import now** runs an import. **Recent import results** shows errors. ### The uploads folder is full Patterm keeps at most 10 MiB per file, 256 MiB in total and 1000 files, and removes files older than seven days on the next upload. If space runs out sooner, delete unused files from `uploads/` in the data directory. Save anything lasting in the project itself. ## Desktop app ### The window is grey or blank Patterm uses Electron's automatic Linux windowing by default. If you set `PATTERM_ENABLE_WAYLAND=1` and the window stays grey, unset it. As a diagnostic, `PATTERM_DISABLE_GPU=1` can help show whether the compositor is at fault, but it does not fix every case. The launch mode is written to `debug.log` in the data directory. ### Quit asks me to confirm Closing the desktop window quits Patterm, and quitting stops every agent and command. The confirmation says how many. Choose **Quit and stop all** to continue. ## Related - [Linux server](https://patterm.com/docs/linux-server.md) - [Browser and phone access](https://patterm.com/docs/browser-and-phone.md) - [Your MCP servers](https://patterm.com/docs/mcp-servers.md) --- This is one page of the Patterm documentation. The index of every page is at https://patterm.com/llms.txt.