help

Troubleshooting

The failure modes most users hit in their first week, and how to unstick each.

Install

brew install pipemason says "No available formula"

Pipemason isn't in Homebrew Core — it ships in a tap. Use the fully-qualified install (Homebrew auto-taps on first install):

brew install crashbytes/tap/pipemason

Or tap once then install bare:

brew tap CrashBytes/homebrew-tap
brew install pipemason

pipemason: command not found after install

The binary landed in $HOME/.local/bin/pipemason (for the curl installer) or $(brew --prefix)/bin (for brew / scoop) but those aren't on your PATH. Add them to your shell profile:

# zsh / bash
export PATH="$HOME/.local/bin:$PATH"
# fish
fish_add_path $HOME/.local/bin

Auth + pairing

pipemason login hangs forever

The runner polls every 2s waiting for you to enter the 9-character code at pipemason.com/pair. Check:

• Are you signed in on pipemason.com in the browser? The /pair page redirects to sign-in otherwise.
• Did you enter the code with the dashes (ABC-4D7-WXY) or paste it raw? Both work, but case matters.
• Is the browser blocking analytics / network requests? The pair page needs a working /api/pair fetch.

pipemason verify returns 401

Your pairing token is expired or revoked. Re-pair:

pipemason login --force

Runs

ANTHROPIC_API_KEY is not set

The runner reads the key from shell env at every invocation. Make sure it's exported in your active shell, not just in a file you haven't sourced:

echo $ANTHROPIC_API_KEY        # should print sk-ant-…

Runner can't push the branch

Two common causes:

• GitHub isn't connected. Reconnect on /dashboard/settings.
• The repo you're running in isn't in the "connected repos" allowlist. Add it on the same settings page.

Anthropic returned 429

Token bucket exhausted on your Anthropic account. The runner will retry with exponential backoff up to the per-phase budget. If you're hitting limits regularly, raise the limit on your Anthropic console or lower parallelism in config.yml.

A phase escalated

See Handling escalations. Tl;dr: read the failing artifact, edit the upstream artifact, pipemason resume <run-id>.

Dashboard / web

Dashboard shows no runs

You're signed in but the dashboard is blank? Check the active scope (top-left of the dashboard). If you're looking at a scope your runs don't belong to, switch scopes. If you don't see a scope picker and the page is empty, your account is in an org you don't have the role to view — talk to the org owner.

Run detail stays on "ws connecting"

The websocket couldn't open. The run-detail screen falls back to 10s polling automatically, so data still flows — just not live. Likely causes: corporate proxy stripping wss://, VPN blocking api.pipemason.com, or a browser extension blocking WebSockets.