pattermDocsGitHub

Troubleshooting

View as Markdown

Fixes for the problems people hit most often, using the messages Patterm shows.

For anything on a server, start with the service log:

systemctl --user status patterm.service
journalctl --user -u patterm.service -n 100 --no-pager

Install and update##

The installer says the service is running##

the background service is running; rerun with --update to replace and restart it

Rerun the installer with --update. See Linux server.

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.

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##

Patterm is already using <directory>, 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.

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:

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.

Commands fail while Patterm restarts##

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##

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.

Browser access##

Request origin is not allowed##

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 <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://<name>/. 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##

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.

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

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.