Troubleshooting and Support¶

Use this page when a command fails, funds look stuck, login feels unstable, or support asks for diagnostics. Start with the simple commands. Drop into the advanced commands only when the CLI or support asks for them.

First checks¶

Run these from the same machine and Bullpen account that saw the error:

bullpen upgrade
bullpen fix --refresh
bullpen support

bullpen fix --refresh checks whether your account is ready to trade, can recover locally, needs login, or needs support. It prints one next action.
bullpen support writes a redacted diagnostic artifact and prints a copy/paste summary for Bullpen support.
Use bullpen status --output json, bullpen doctor auth --output json, bullpen doctor wallet --output json, or bullpen polymarket wallet-audit --refresh --output json only when the fix or support output asks for them.

Typed error JSON¶

When a command supports --output json, use it for support reports. Error JSON may include:

error for the top-level failure.
chain or caused_by for sanitized cause details.
hint or recovery_command when the CLI can suggest the next command.
recovery for the canonical next step on Polymarket money-path failures.
recovery_plan for the shared account-level plan from fix, recover polymarket, support, and wallet diagnostics.
signing_capability for whether the active signer can authorize the non-submitting signing check that money commands need.
market_state for preview-only Polymarket states such as market_resolved, closed_or_resolved, or orderbook_unavailable. When it appears with would_submit: false, no order was submitted.
wallet_readiness for the on-chain/server-selected wallet state. A status such as user_action_available describes the state; a resolution_owner such as user or bullpen_support describes who can act.
clob_readiness or clob_route_readiness for off-chain order-credit and CLOB route checks. support emits clob_readiness; polymarket wallet-audit emits clob_route_readiness. If terminal: true and resolution_owner: "bullpen_support", stop retrying money-moving commands and attach the support bundle named in support_artifact.
selected_wallet, selected_wallet_route, clob_readiness.selected_wallet, or clob_route_readiness.selected_wallet for the wallet Bullpen will use for Polymarket trading.
command-specific fields such as relayer trace IDs, wallet kind, selected route, dry-run state, or status-page context.

Unknown fields are allowed. Treat absent optional fields as null. See the JSON output contract and Output and Errors.

Prefer recovery.next_action or recovery_plan.next_action when present. For bullpen support --output json, next_action is the account recovery step and support_next_action tells you what to do with the generated artifact.

Auth error codes¶

Use the typed auth code before choosing the next action. Do not send every auth-looking error through a fresh login flow.

Code	Meaning	Safe next action
`AUTH_REFRESH_PERSISTENCE_FAILED`	Refresh succeeded, but the rotated credentials could not be saved durably.	Stop unattended commands, keep the same `BULLPEN_HOME`, make the Bullpen home writable, and run `bullpen doctor auth --output json` before retrying money-moving commands.
`AUTH_REFRESH_REJECTED_LOGIN_REQUIRED`	The auth service rejected the refresh token.	Run `bullpen login`; this is the refresh failure class that needs a human device login.
`AUTH_REFRESH_TRANSIENT_FAILURE`	Refresh failed because of a retryable network or service problem.	Retry the command before starting a new login.
`USERGATE_AUTH_REJECTED_AFTER_REFRESH`	Bullpen account services still rejected the session after one refresh.	Capture `bullpen doctor auth --output json` and the failing command JSON; escalate with support evidence instead of repeatedly logging in.
`USERGATE_AUTH_REJECTED_NO_REPLAY`	Bullpen account services rejected auth for a non-idempotent mutation such as email OTP send, wallet private-key import, wallet selection/nickname/visibility, notification mark/preference, portfolio or PnL refresh, pre-swap transfer, Solana submit/record/sponsored transfer, deposit-wallet deploy/reregister, Polymarket contract-wallet selection, wallet-tracker add/remove, Turnkey API-key revoke, or copy-trading, and Bullpen did not replay it.	Run the `next_action` diagnostics and inspect account/order state before any manual retry.
`signing_capability.signing_capability: "turnkey_resource_missing"`	Credentials decrypt, but the active signer cannot sign through the required Turnkey path.	Run `bullpen doctor auth --output json`, then `bullpen support`. Do not loop on `bullpen login` unless diagnostics report `login_required`.
`PEAR_READ_SESSION_MISSING_NO_REFRESH` or `PEAR_READ_SESSION_EXPIRED_NO_REFRESH`	Pear pair reads need a cached Pear session and the CLI did not refresh it during the read.	Run `bullpen hl pair login --yes`, then rerun the read. Do not run live setup unless `pair status` or `pair setup --preview` reports setup is incomplete.
`PEAR_MUTATION_AUTH_REJECTED_NO_REPLAY`	Pear rejected auth after a live Pear write request was submitted.	Inspect `bullpen hl pair positions --output json` and `bullpen hl pair orders --output json` before retrying.
`HYPERLIQUID_COPY_RAW_TOKEN_AUTH_REJECTED`	A raw-token Hyperliquid copy context was rejected. Raw-token contexts cannot refresh Bullpen auth.	Inspect `bullpen doctor auth --output json` and retry through normal CLI auth. Do not start blind device login unless diagnostics report `requires_login: true`.
`TRADE_SERVER_REDEEM_AUTH_REJECTED_NO_REPLAY`	Bullpen rejected auth on a redeem path that cannot be replayed safely.	Run `bullpen doctor auth --output json`, then inspect redeem dry-run and wallet audit output before retrying manually.
`TRADE_SERVER_AUTH_REJECTED`	Bullpen rejected the refreshed customer session.	Capture `bullpen doctor auth --output json` and the failing order JSON, then escalate with support evidence.

When an error JSON object includes requires_state_inspection: true, do not auto-retry the live command. That field means the CLI deliberately avoided a blind replay because operation state may need to be inspected first.

Common routes¶

Problem	Start with	Deeper guide
Login, expired session, missing local auth files, or Turnkey resource errors	`bullpen fix --refresh`	Auth And Config Recovery
Browser login, missing device-code page, or copied credential bundle friction	`bullpen login --no-browser`, then `bullpen fix --refresh`	Auth And Config Recovery
Test, CI, or support run uses the wrong profile	`bullpen config show --output json`, then verify `BULLPEN_HOME` and `BULLPEN_CONFIG`	Auth And Config Recovery
Bullpen support asks for the hidden trading-route diagnostic	Treat it as configuration evidence only; capture `doctor auth` and the failing order JSON for a live session rejection.	Authentication
Homebrew refuses the Bullpen tap or formula as untrusted	`brew trust --formula bullpenfi/tap/bullpen`, then retry install or upgrade	Install friction
Wallet kind, stale account route, or assets on another Polymarket wallet	`bullpen recover polymarket`	Wallet Routing And Funds Recovery
Polymarket buy/sell fails with a support-required wallet error	`bullpen support`	Wallet Routing And Funds Recovery
Polymarket approval, activation, or trade says the wallet is not registered	`bullpen support`, then follow any exact repair command it prints	Wallet Routing And Funds Recovery
`PM_LEGACY_DEPOSIT_WALLET_PENDING_RECOVERY` appears in `status`, `doctor wallet`, or `wallet-audit`	`bullpen support`	Funds are safe on-chain at a legacy pre-beacon Deposit Wallet. Do not repeatedly retry approve, activate, reregister, or trading for that wallet.
Native Polygon USDC appears on-chain but `wrap` or balances report zero	`bullpen recover funds --dry-run --output json`; execute only if the plan says `resolution_owner: "user"`, otherwise run `bullpen support`	Wallet Routing And Funds Recovery
Upgrade or stale binary errors	`bullpen upgrade`, then rerun `bullpen --version` and the failing command	Quickstart upgrade notes
Redeem or resolved-position recovery	`bullpen recover redeem --dry-run --output json`	Redeem and relayer issues
Polymarket preview reports `POLYMARKET_MARKET_RESOLVED`, `market_state: "market_resolved"`, or `market_state: "closed_or_resolved"`	`bullpen recover redeem --dry-run --output json`	Redeem and relayer issues
Polymarket preview reports `POLYMARKET_ORDERBOOK_UNAVAILABLE` or `market_state: "orderbook_unavailable"`	`bullpen polymarket discover`	Search for a currently tradable market or wait for a live orderbook. If the market is resolved and you hold tokens, use redeem recovery instead of retrying a sell preview.
Unsupported withdraw, wrong-chain deposit, wrong-token deposit, or exchange-address confusion	`bullpen funds diagnose-deposit --tx <TX_HASH> --chain <CHAIN> --token <TOKEN> --address <RECIPIENT_ADDRESS> --output json`	Wallet Routing And Funds Recovery
Hyperliquid balance, order, deposit, agent slot, or active-wallet state is unclear	`bullpen hl status --output json`, then `bullpen hl balances --output json` and `bullpen hl orders --output json`	Hyperliquid account diagnostics
Hyperliquid spot pair, spot order, or spot TWAP state is unclear	`bullpen hl spot pairs --search <TOKEN> --output json`, then `bullpen hl spot orders --pair <PAIR> --output json`	Spot (Hyperliquid)
Hyperliquid spot IOC returns `HYPERLIQUID_IOC_NO_MATCH`	Refresh `bullpen hl spot orderbook --pair <PAIR> --output json`, adjust price, rerun `--preview --output json`, then submit only if the preview still matches your intent	Spot (Hyperliquid)
Hyperliquid command is unavailable or live submit is blocked	`bullpen experimental enable hyperliquid`; live mutations also need `bullpen experimental enable hyperliquid_trading`	Hyperliquid first commands
Telemetry, privacy, local logs, or opt-out behavior	Review what is collected before attaching logs	Telemetry
Exit code, typed JSON, or retry behavior is unclear	Capture the command with `--output json` and record the process exit code	Output and Errors

Wallet routing¶

Do not force a wallet kind unless the audit or support confirms it. Polymarket money-handling commands use the server-authoritative wallet route and fail closed when the selected Safe/Proxy/Deposit Wallet state is inconsistent.

Use bullpen support first when an error is support-owned or marked requires_state_inspection: true. Use the advanced JSON bundle or wallet-audit commands only when the support handoff or Bullpen support asks for them. The Wallet Routing And Funds Recovery guide, Trading guide, and Safe to Deposit Wallet migration guide cover normal routing, diagnostics, and support-directed migration paths.

If a Polymarket order fails with POLYMARKET_SERVER_SAFE_CLOB_REJECTED, run bullpen support and attach the generated artifact to support. Do not use --wallet as a bypass. Do not switch wallet kind unless Bullpen support, or a CLI repair verdict, gives the exact kind.

If bullpen status, bullpen doctor wallet, or bullpen polymarket wallet-audit reports PM_LEGACY_DEPOSIT_WALLET_PENDING_RECOVERY, the CLI found funds at a legacy pre-beacon Deposit Wallet address. The funds are safe on-chain, but the state is not self-service. Do not retry approve, activate, reregister, or trading for that wallet. Run bullpen support and wait for Polymarket/Bullpen recovery status.

If a Deposit Wallet is already selected and deployed but Polymarket returns POLYMARKET_RELAYER_WALLET_NOT_REGISTERED or "wallet registry validation failed", this is a relayer-registry issue, not a normal first-trade activation issue. Run:

bullpen support
bullpen polymarket reregister-deposit-wallet --force-relayer-refresh --yes --output json

If the forced refresh does not return status: registered, contact Bullpen support with the command output. Support may need to repair the relayer registry record before approve, activate, or trading can work.

Run bullpen doctor auth --output json when auth diagnostics mention AUTH_CREDENTIALS_FILE_CORRUPT, credentials.json.enc, or credential_salt.bin, and preserve the JSON output for support. Run bullpen login to start a fresh session. Login moves unreadable local auth files aside before re-authenticating.

For copied homes, first verify the portable-auth set: copy credentials.json.enc, credential_salt.bin, and keys/ together, keep the same absolute BULLPEN_HOME, set the same BULLPEN_USERNAME_OVERRIDE when the destination username differs, and run bullpen doctor deploy-auth --output json on the destination host. Do this before deleting local auth files.

Keep copied-home auth on a local persistent filesystem unless you have validated the exact runtime. NFS, cloud-synced folders, and container volumes can create durability or partial-sync failures that look like auth corruption.

If browser launch is the only blocker, avoid resetting local state. Print the device-code URL and code instead:

bullpen login --no-browser

Use bullpen logout --force && bullpen login only when diagnostics or support identify local credential reset as the recovery. This deliberate local reset does not repair server-side account or wallet-routing state; collect doctor auth and wallet-audit output if the fresh login still cannot trade.

bullpen doctor auth --repair --yes is a destructive support-facing repair path for the corrupt local keypair file case when doctor auth says repair is applicable. It is not the generic fix for missing or corrupt encrypted credentials or salt files. Run plain bullpen doctor auth --output json first and keep the JSON output for the ticket.

Config and profile isolation¶

Wrong-profile issues usually come from setting only BULLPEN_CONFIG or only BULLPEN_HOME. Credentials resolve through BULLPEN_HOME; config resolves through --config, then BULLPEN_CONFIG, then the profile default.

Create or inspect the profile before logging in:

export BULLPEN_HOME="$PWD/.bullpen-support-home"
export BULLPEN_CONFIG="$BULLPEN_HOME/config.toml"
mkdir -p "$BULLPEN_HOME"
bullpen config init
bullpen config show --output json

If an explicit config path is missing, Bullpen fails closed. That is expected: fix the path, create the config, or unset BULLPEN_CONFIG before using the default profile. See Configuration and the generated config reference.

Install and upgrade friction¶

Prefer the native installer for fresh machines when you want to avoid Homebrew tap-trust prompts:

curl -fsSL https://cli.bullpen.fi/install.sh | sh

For Homebrew installs, trust the Bullpen formula before retrying if Homebrew refuses the tap or formula:

brew trust --formula bullpenfi/tap/bullpen
brew update
brew upgrade bullpen
brew link --overwrite bullpen

Use bullpen upgrade after installation to exercise the supported upgrade surface for the detected install method. Homebrew and npm installs delegate to their package manager first; direct installs use GitHub releases. See upgrade for exact options.

Redeem and relayer issues¶

Start with the guided recovery dry-run:

bullpen recover redeem --dry-run --output json

For large accounts, or when the Polygon RPC provider reports HTTP 429 or rate limits during redeem discovery, test a smaller auto-discovery batch:

bullpen recover redeem --limit 20 --dry-run --output json

If the guided output directs you to support, create one redacted artifact:

bullpen support

bullpen support does not move money. It collects the current account evidence needed for a support ticket without asking you to assemble several raw command outputs.

--limit applies only to auto-discovered redeem candidates. Use --condition-ids when support gives you exact condition IDs.

In JSON output, inspect redeem_plan before deciding whether to submit or retry. The most useful fields are case_type, payout_proof_source, execution_route, and verification_plan.expected_value_movement. Cases such as gamma_missing_onchain_recovered, discovery_rate_limited, relayer_rejected, and mined_no_value_moved tell support whether the issue is market metadata, provider throttling, relayer rejection, or a mined transaction that did not prove value movement.

If live submit fails after a dry-run builds a redeemable plan, run bullpen support and include the failed command's short error summary in the ticket. Do not keep retrying repeated STATE_FAILED submits without support review. The Trading guide documents the public redeem and closeout surfaces.

The expert bullpen polymarket redeem command remains available when support provides exact condition IDs or asks for its detailed output.

Native USDC and pUSD conversion¶

Polymarket prediction-market trades use pUSD collateral. If your wallet holds Polygon native USDC, the CLI can preview and, when supported for your account, convert native USDC to USDC.e before wrapping to pUSD:

bullpen polymarket wrap <AMOUNT> --preview --output json

Upgrade first if native USDC is visible on-chain but the CLI reports zero. The latest CLI verifies the native-USDC token directly when the portfolio service omits that row. If preview still reports zero or the live wrap fails, attach the preview JSON, wallet-audit --refresh --output json, and the live error JSON to support.

Unsupported deposit assets, including assets that are not part of the Polymarket pUSD/USDC.e/native-USDC conversion path, still require web-app or support guidance. Do not retry blind wraps for unsupported tokens.

Withdraw and recovery boundaries¶

The CLI supports only narrow withdraw routes, such as Polygon Deposit Wallet USDC.e when the account and destination are compatible. It refuses unsupported token or chain combinations instead of using retired bridge routes.

Use the Bullpen web app for normal deposits and unsupported withdrawals. Use funds diagnose-deposit and wallet-audit --refresh for evidence when funds were already sent to a wrong chain, wrong token, signer EOA, bot Safe, imported wallet, or exchange address. See Trading withdraw guidance.

Hyperliquid experimental flags¶

All bullpen hyperliquid / bullpen hl commands require:

bullpen experimental enable hyperliquid

Live mutating Hyperliquid commands additionally require:

bullpen experimental enable hyperliquid_trading

Use --preview or --dry-run before live Hyperliquid mutations. Support/QA-only builder override flags are env-gated and should not be used for normal customer setup. See Perps (Hyperliquid) and the experimental reference.

Privacy and support tickets¶

Do not share private keys, seed phrases, JWTs, API tokens, or full unredacted config files. If support asks for logs, prefer the smallest command-specific log that reproduces the issue and review it before attaching.

Telemetry and local-log behavior are documented in Telemetry. For help, open a Bullpen support ticket:

https://bullpen-help.freshdesk.com/support/tickets/new