Troubleshooting

Diagnose and resolve common issues with the CLI and runner.

pipemason: command not found

The install location is not on your $PATH. For an npm global install, find the prefix and add its bin directory to your shell config:

npm config get prefix
# append /bin to that path and add it to your shell profile, e.g.:
export PATH="$(npm config get prefix)/bin:$PATH"

If you installed via the single-use curl ... | bash command, the binary lands at ~/.local/bin/pipemason — make sure ~/.local/bin is on your PATH.

GitHub token expired

GitHub tokens are non-expiring by default but can be revoked. If a git operation fails with this error, reconnect: visit pipemason.com/settings, click Disconnect, then Connect GitHub again to re-authorize the OAuth app.

rate_limited

You hit a cloud-side rate limit (roughly 60–120 requests per minute, depending on the route). In normal use you should never see this — wait a moment and retry. If it persists, something is off; open a support ticket. If you are deliberately load-testing, email support@pipemason.com first.

run_quota_exceeded or repo_quota_exceeded

You reached a Free-tier cap — 10 runs per calendar month, or the 1-repo limit. Upgrade your plan, or wait until the next calendar month for the run quota to reset. See plan limits on the FAQ.

Run does not show on the dashboard

The runner is most likely not connected to the cloud. On startup, a connected runner logs:

cloud: registered run <id>

If you instead see connecting to cloud control plane with no following registration line, your runner token may be invalid. Re-pair the machine:

pipemason login

A run escalated

The monitor escalates rather than auto-resolving anything ambiguous — rebase conflicts, gate failures it cannot recover from, or contract disagreements between domains. The run pauses and waits for you.

pipemason status     # show STATE.md and the escalation block
# ...fix the issue in your repo...
pipemason resume     # continue from where the run stopped

More help

For the meaning of specific codes, see Error & status codes. For anything else, email support@pipemason.com and include your Clerk user id (shown in the top right of the dashboard, or in any escalation message) so we can find your runs.