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¶

Start with passive checks:

bullpen status
bullpen doctor auth

Run bullpen upgrade only when the error reports a stale binary.
Run bullpen fix --refresh only when status, auth diagnostics, or the failed command asks for refreshed readiness evidence. It checks whether your account is ready to trade, can recover locally, needs login, or needs support, and prints one next action.
bullpen support bundle --output json writes a redacted diagnostic artifact and prints a JSON report with the artifact path and delivery status. This file is on this machine and has not been uploaded; attach it to your support ticket. Run bullpen support when you need a copy/paste handoff. The bundle is passive: it does not refresh auth, sign a test digest, or prove signing authority.
Support-bundle evidence is separate from refreshed wallet and order credit evidence. Run bullpen polymarket wallet-audit with --refresh, --include-order-credit, and --output json only when the CLI or Bullpen Support asks for that active evidence.
Use JSON variants such as 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.
delivery for support artifacts. delivery.state: "local_file_not_uploaded" and delivery.uploaded: false mean the file is on this machine and has not been uploaded.
originating_context for recent support handoffs. When present, it contains only a privacy-safe command family and typed error code from a failure in the last 24 hours, not raw arguments or error text.
auth_incident for device-login and email-verification attempts. Read stage, safe_to_retry, resolution_owner, next_command, and support_code. A local attempt_id does not imply service-side correlation.
signing_capability for signing-path evidence. checked: false means the command did not run a signing probe; it does not prove that the active wallet can sign, and it does not diagnose Turnkey resource errors. Only treat signing_capability.signing_capability as probe evidence when checked is true.
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 selected trading 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.
legacy_deposit_wallet_recovery or polymarket_legacy_deposit_wallet_recovery for legacy pre-beacon Deposit Wallet evidence. Do not assume every legacy Deposit Wallet case is unrecoverable locally. Run bullpen recover funds --dry-run --output json; the plan marks each leg as supported, no_op, unsupported, backend_only, or unknown.
order-route readiness fields such as clob_readiness or clob_route_readiness for order credit and Polymarket order-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 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 bundle --output json, next_action is the account recovery step and support_next_action tells you what to do with the generated artifact. Attach the JSON file named by artifact_path; a local path by itself does not send the file to Bullpen.

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 failed closed because rotated credentials were missing, blank, or could not be saved and read back 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.	After `bullpen doctor auth --output json` reports this code, 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.
`AUTH_VERIFY_EMAIL_OTP_REQUEST_OUTCOME_UNKNOWN`	The email-code request was sent once, but its service outcome was not confirmed. The CLI did not replay it.	Run `bullpen support bundle --output json` and attach the generated artifact. Do not request another code or repeat login until support inspects the attempt.
`AUTH_DEVICE_LOGIN_RETRY_BUDGET_EXHAUSTED` or `AUTH_DEVICE_LOGIN_TERMINAL_STATE`	Device login did not complete within its bounded poll window, or the service reported a terminal attempt state.	Follow `auth_incident.next_command`. When support is required, attach the generated artifact instead of starting another login loop.
`signing_capability.checked: false`	A passive diagnostic reported no signing result. Plain `doctor auth` and `support bundle` use this shape.	Use token, credential, wallet-readiness, and failing-command fields for the next step. Do not treat this as proof of signing readiness or as a Turnkey resource diagnosis.
`signing_capability.checked: true` with `signing_capability.signing_capability: "turnkey_resource_missing"`	An active signing probe or money-command signing path reached Turnkey and found the required resource missing.	Capture the failing command with `--output json`, then run `bullpen support bundle --output json` and attach the generated artifact. 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`.

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 active-command Turnkey resource errors	`bullpen status`, then `bullpen doctor auth`; run `bullpen fix --refresh` only when diagnostics request refreshed evidence	Auth And Config Recovery
Browser login, missing device-code page, or copied credential bundle friction	`bullpen status --output json`, then `bullpen doctor auth --output json`; use `bullpen login --no-browser` only when diagnostics require login	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 an advanced support 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
Assets on another Polymarket wallet or funds-route confusion	`bullpen recover funds --dry-run --output json`	Review the funds recovery plan, then submit only after review with `bullpen recover funds --yes`.
Wallet kind, stale account route, account readiness, or routing disagreement	`bullpen recover polymarket --refresh --output json`	Use this for account/auth repair only. For asset recovery, start with `bullpen recover funds --dry-run --output json`.
Polymarket buy/sell fails with a trading-wallet rejection	`bullpen fix --refresh`	Follow the single next action it prints.
Polymarket buy/sell fails with another terminal wallet-routing error	`bullpen recover polymarket --refresh --output json`	Wallet Routing And Funds Recovery
Polymarket approval, activation, or trade says the wallet is not registered	`bullpen support bundle --output json`, then follow any exact repair command it prints	Wallet Routing And Funds Recovery
The CLI reports legacy Deposit Wallet recovery is pending	`bullpen recover funds --dry-run --output json`	Use the plan outcome. The plan may move proven legacy Deposit Wallet assets locally or direct you to support. Passive `bullpen status` does not probe remote wallet state.
Native Polygon USDC appears on-chain but `wrap` or balances report zero	`bullpen recover funds --dry-run --output json`; execute only when the plan says the CLI can move funds from the intended source to the intended destination. Otherwise run `bullpen support bundle --output json`	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 submission 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 submission 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
Hyperliquid copy update reports `unsupported` for `--execution-mode` or `--confirm-each`	Treat it as a missing service contract, not an auth or account issue. Leave execution mode unchanged and retry only after a CLI/service update documents support.	Hyperliquid copy trading
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 recover polymarket --refresh --output json first for wallet routing disagreement errors. Use bullpen fix --refresh first for trading-wallet rejections. Use bullpen support bundle --output json when an error is support-handled or marked requires_state_inspection: true. Use bullpen polymarket wallet-audit --refresh --include-order-credit --output json only when the support handoff or Bullpen support asks for active order-credit evidence. 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 reports a trading-wallet rejection, run bullpen fix --refresh and follow its single next action. If another selected wallet route is rejected, run bullpen recover polymarket --refresh --output json. 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 legacy Deposit Wallet evidence appears, preview funds recovery instead of switching wallets or repeating setup commands:

bullpen recover funds --dry-run --output json

The plan can recover eligible assets from selected or non-selected owned Safe, Proxy, current Deposit Wallet, deployed legacy Deposit Wallet, and CLI-proven locally signable owned EOA sources. Direct-address submit requires CLI-proven signing authority and enough native gas. Other address-source routing requires Bullpen support.

Recovery does not change the selected trading wallet. Live submit refreshes and rechecks the source identity, destination identity, and exact transfer details, then validates the full plan before the first transfer. Submit only when the preview says the CLI can move the funds and the destination is correct.

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

bullpen support bundle --output json

Attach the generated support artifact. This file is on this machine and has not been uploaded. Do not retry approve, activate, wallet selection, registration, or money movement until Bullpen support confirms the external route is repaired. Wallet-status fields such as deployed or allowed do not override the external registration rejection.

Run bullpen status --output json and 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 only when diagnostics report that login is required or local credential recovery needs 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 diagnostics require login and browser launch is the only blocker, avoid resetting local state. This is a non-runnable sequence: print the device-code URL and code only when diagnostics require login and browser launch is the blocker.

bullpen login --no-browser

Use bullpen logout --force 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. After the reset, rerun bullpen status --output json and bullpen doctor auth --output json, then start bullpen login only if diagnostics require it. Collect doctor auth and wallet-audit output if a 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 still requires typing REPAIR at the prompt; --yes alone is not enough. 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.

This is a non-runnable sequence: create or inspect the profile before logging in, and run config init only when the isolated config is missing or intended.

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¶

This is a non-runnable sequence: run the native installer only for a fresh machine when you want to avoid Homebrew tap-trust prompts.

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

This is a non-runnable sequence: run the Homebrew commands only for a Homebrew install when 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.

For install-method diagnosis, BULLPEN_INSTALL_METHOD_OVERRIDE can assert one of direct, homebrew, or npm for a single command. This is a non-runnable sequence: run it only when diagnosing direct-install upgrade behavior.

BULLPEN_INSTALL_METHOD_OVERRIDE=direct bullpen upgrade --output json

The override cannot redirect an upgrade to a different installation. Bullpen rejects invalid values and rejects homebrew or npm unless the running executable and the package manager's reported install root agree. Leave the variable unset during normal use.

Redeem and submission 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 bundle --output json

bullpen support bundle --output json does not move money, refresh auth, sign a test digest, or prove Turnkey signing authority. It collects the current account evidence needed for a support ticket without asking you to assemble several raw command outputs. This file is on this machine and has not been uploaded; attach the JSON file to your support ticket.

--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, external submission 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.

If a live redeem reports post-submit uncertainty or prints a redeem operation ID, do not replay the redeem. Inspect the existing operation with this read-only status command instead:

bullpen polymarket redeem-status <operation-id-or-tx-or-trace> --output json

pending_unknown means indexing or settlement evidence is not final yet. confirmed_positive_payout and confirmed_zero_payout do not need a retry. Escalate reverted_receipt, missing evidence, wrong_wallet_settlement, or contradictory_evidence with the status JSON.

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 USDC.e, the CLI can preview wrapping it to pUSD:

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

If your wallet holds Polygon native USDC, start with read-only recovery planning instead:

bullpen recover funds --dry-run --output json

When supported for your account, the plan can convert native USDC to USDC.e before wrapping to pUSD. Otherwise it keeps the case in diagnostics or support handoff territory instead of treating native USDC as directly wrappable USDC.e.

Upgrade first if native USDC is visible on-chain but the CLI reports zero. The latest CLI verifies the native-USDC token directly when account balance data 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.

For a live pre-swap, the CLI requires proven native-USDC decrease and USDC.e increase. It refuses zero movement and output below 99% of the approved input. If output is within that 1% bound, the CLI wraps only the proven available amount and reports both requested and submitted values. If JSON reports submission_state: "outcome_unknown" or safe_to_retry: false, do not repeat the money command until the emitted diagnostic command reconciles the wallet state. Human output reports the same submission state, resolution owner, retry safety, next action, and next command as JSON. A pre-swap that was not submitted directs you to the read-only deposit diagnostic. In JSON, older compatibility errors may set classification_source to legacy_string_fallback; that means the CLI had to classify an older text-only error message instead of receiving a structured error code:

bullpen funds diagnose-deposit --chain polygon --token usdc --output json

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, CLI-proven locally signable owned EOA, bot Safe, imported wallet, or exchange address. See Trading withdraw guidance.

Hyperliquid experimental flags¶

All bullpen hyperliquid / bullpen hl commands require: This is a non-runnable sequence: enable the namespace only when you intend to use experimental Hyperliquid commands.

bullpen experimental enable hyperliquid

Live mutating Hyperliquid commands additionally require: This is a non-runnable sequence: enable live Hyperliquid trading only when you intend to use mutating Hyperliquid commands.

bullpen experimental enable hyperliquid_trading

Use --preview or --dry-run before live Hyperliquid mutations. Support-gated 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