Troubleshooting

Troubleshooting

Boon should fail loudly when identity, wallet, relayer, or policy state is uncertain. Use this page to decide whether to retry, switch surfaces, or ask for operator help.

Sender cannot send

Wallet is short on Base USDC

Use Coinbase Onramp or transfer Base USDC to the sender wallet. The app funds the wallet; it does not atomically call Boon.tip() through Onramp.

Approval or send transaction failed

Check that the wallet is on Base mainnet, has ETH for gas, and approves only the exact USDC amount being sent. Do not retry with a different token, chain, or contract.

Handle is rejected

Handles must canonicalize to github:<user> or x:<user>. Normalize before hashing. If the intended recipient is ambiguous, stop and confirm the handle.

Recipient cannot claim

OAuth verification fails

The recipient must sign in with the same provider that received the boon. A tip to github:alice cannot be claimed through X, and a tip to x:alice cannot be claimed through GitHub.

Wallet link fails

Retry after confirming the connected wallet address is the intended receiving wallet. The public v1 link is effectively permanent for normal users; recovery uses the operator-assisted relink() path and only affects future pushes.

Relayer is down or disabled

The UI should say so instead of pretending gasless claim is live. The recipient should wait for relayer recovery or follow maintainer-provided manual transaction guidance.

Claim shows no funds

Possible causes:

• the boon was sent to a different provider prefix (github: vs x:)
• the sender used a typo or different username
• the subgraph has not indexed the latest block yet (see Data looks stale)
• the handle was already linked and the boon pushed directly to that linked wallet

The recipient FAQ in HOW_TO_CLAIM.md covers the broader claim experience — verification, lost passkeys, switching wallets via relink(), and what to do if you never claim. Read it before escalating to the operator.

Agent / CLI failures

boon doctor fails

Run:

boon wallet current
boon doctor --json

Common fixes are selecting an OWS wallet, funding the OWS address with Base USDC and gas headroom, setting a reachable RPC URL, or lowering the requested tip below the local guardrails.

OWS policy rejects the send

Treat this as a stop condition. The operator should either approve a new explicit policy/plan id or reduce the tip to fit the existing policy. Do not bypass OWS policy checks or use raw private keys.

--yes fails without an approval id

This is expected. Agent sends require:

boon tip --yes --approval-id <human-approved-policy-or-plan-id> <handle> <amount> "<note>"

Cooldown or cap rejects the tip

Boon keeps local spend and cooldown guardrails under ~/.boon/. If a tip exceeds the configured cap or cooldown, return a proposal marked needs_check instead of sending.

API and x402 issues

Free endpoint works but paid endpoint fails

Detailed graph reads use x402. Confirm the client understands the 402 Payment Required response, can pay on Base, and retries with the payment proof. Claiming and recipient help must not require x402.

Data looks stale

The app and API depend on subgraph indexing. Compare the latest transaction block to the indexed subgraph block before assuming contract state is wrong. The Data layer concept explains the entity model and the _meta { block { number } } check for diagnosing index lag.

Safety stop conditions

Stop instead of retrying when:

• a user provides a private key in chat
• the chain is not Base mainnet
• the asset is not Base USDC
• the contract address differs from the documented Boon deployment
• the recipient identity is ambiguous
• an agent wants to send without explicit approval or policy coverage