Troubleshooting

Start with button-runner status on the computer that runs your tools (on Windows: & "$env:LOCALAPPDATA\Button\button-runner.exe" status). It shows the version and whether this computer is paired, running and set to start at login. The log is the next stop:

• macOS: ~/Library/Logs/button-runner.log
• Linux: journalctl --user -u button-runner
• Windows: %LOCALAPPDATA%\Button\runner.log

The tool page says Offline

The runner isn't connected. Check that:

• The computer is on, awake and online.
• You're logged in. On Linux the runner stops when you log out, unless you ran sudo loginctl enable-linger $USER.
• button-runner status says it's running. If not, run button-runner restart. If that says the background service isn't installed, run button-runner install.
• Your network lets it reach button.bitgate.dev, see firewalls and proxies below.

The tool page says Busy

A computer runs one job at a time. Wait for the current run to finish and press Run again.

"The runner didn't respond in time"

The runner turned the run down and nothing ran. The usual reasons:

• The manifest isn't approved on this computer. This happens after you move to another computer, or when a manifest was published without the setup page. Approve it with button-runner approve manifest.json, see the manifest reference. The log shows a line ending in bad_manifest.
• A value didn't pass the form's rules on the runner, which checks them again. The log says which one.
• The runner was already busy, or the computer has started 500 jobs today (UTC).

The run failed

The program exited with an error, or the runner stopped it. Look for:

• A value that starts with -. Values can't start with a dash; the run fails before the program starts.
• An optional field without a value that is part of the command. Give it a default on the setup page.
• A required result that never showed up. Your program has to write its results into the output folder it gets as an argument.
• The time limit. Runs stop after the tool's time limit, at most 30 minutes.

To see why, run button-runner setup and use Test run with the same values: it shows the end of the program's output.

My script can't find a program, a setting or a password

Jobs run with the background runner's environment, not your terminal's. On macOS and Linux it gets PATH and the proxy settings from the terminal you installed from, nothing else. Variables exported in a shell profile, such as DATABASE_URL, aren't visible. Read settings from a file next to the script, or add them to the tool's environment on the setup page (env in the manifest). After changing PATH, run button-runner restart from a terminal that has the new value.

People need to send several files

Each file field takes exactly one file, and a tool has at most 8 file fields. For batches, have people upload a ZIP and unpack it in your script.

I edited my script

That's fine. The approval covers the command and the form, not what's inside your script, so the next run uses your edited script.

Pairing problems

• "Get a new code": codes work once and expire after 10 minutes. Copy a fresh install command from https://button.bitgate.dev/app/machine.
• "Your other computer is still running a job": a workspace has one computer, and pairing a new one replaces the old one. That only happens when the old one is idle. Wait for its job to finish and run the same command again; the code stays valid for its 10 minutes.
• "Runner version ... is below the minimum supported version": this runner is too old. Run the install command again; it downloads the latest version before pairing.
• "This computer was replaced by another one in your workspace": someone paired another computer. To use this one again, pair it with a new code.

Publishing a tool

• "Your plan's tool limit is reached": the Free plan has 1 tool. Upgrade at https://button.bitgate.dev/app/billing, then press Publish again. Everything you filled in stays.
• "This setup link was already used": the link works once. Run button-runner setup for a new one.
• The setup page closes itself after 15 minutes without an open tab. Run button-runner setup again.

"Another button-runner is already running on this computer"

Only one runner runs per computer. button-runner status shows its process id. If you started button-runner serve in a terminal, stop it there with Ctrl+C, or leave the background runner to it.

Firewalls and proxies

The runner needs outgoing HTTPS (port 443) to button.bitgate.dev, including a WebSocket connection that stays open. It never needs incoming connections.

Behind a proxy, set HTTPS_PROXY and install again, see Proxies in the install guide. The runner doesn't use PAC files or automatic proxy detection, on Windows either. If your proxy inspects HTTPS with its own certificate, the runner trusts the system certificate store on macOS and Windows. On Linux, add the certificate to the system bundle or set SSL_CERT_FILE.

Moving to a new computer

1. Install on the new computer with a fresh code from https://button.bitgate.dev/app/machine. This replaces the old computer once it's idle; your tools, links and the people you invited stay.
2. Copy the manifests folder from the old computer's settings folder into the new one's: ~/Library/Application Support/button on macOS, ~/.config/button on Linux, %APPDATA%\button on Windows. Or approve each tool's manifest with button-runner approve.
3. Put your scripts and programs at the same paths as before. An approval pins the exact program path and folder, so keep them the same.
4. On the old computer, run button-runner uninstall.