Troubleshooting

Troubleshooting

Cross-SDK FAQ. For per-surface troubleshooting, see each SDK page.

Top-of-funnel issues

”Master keys are no longer accepted”

Both ag_live_sk_* (seller) and ag_treasury_sk_* (Treasury) were hard-cut on 2026-04-27. The platform middleware returns 401 for any request bearing one.

Fix:

agentagon init                                # bootstrap a session
agentagon service pat create --label cli      # for seller calls
agentagon pat create --label buyer-bot        # for buyer calls

Update your env vars / config to use the new PATs.

401 right after minting a PAT

PAT validation propagates through the gate’s auth cache on a short delay. Wait 5-10 seconds and retry. Use agentagon whoami (or the SDK’s whoami()) to confirm the platform sees the token.

treasury_key_missing from a buyer helper

The SDK’s buyer helpers (balance, pay, transfer, list_wallets) talk to Treasury, not Gate, so they need a separate bearer:

client = Client(
    token="ag_pat_...",
    treasury_key="ag_pat_...",   # required for buyer helpers
)

The two tokens can be the same PAT if it has both scopes. For most setups they’re different.

Seller-side issues

Buyers see permit2_allowance_required

The upto scheme requires buyers to hold a one-time on-chain Permit2 allowance for USDC. Public testnet facilitators don’t yet ship gas-sponsoring extensions, so each buyer wallet must approve once. Have buyers run scripts/permit2_approve.py (in the agentagon repo) or call Permit2’s approve() directly.

If you don’t need upto, drop it from schemes and stay on exact.

AgentagonSDKConfigError: facilitator_address is required

You passed schemes=["exact", "upto"] (Python) or schemes: ["exact", "upto"] (Node) without facilitator_address. The upto scheme uses Permit2; buyers’ witnesses bind to a specific on-chain caller. Get the address from your facilitator’s GET /supported.kinds[].extra.facilitatorAddress.

Multi-endpoint seller, transactions attributed wrong

The platform attributes ledger rows by either endpoint_id (when the seller pinned it via the middleware) or by route lookup. A mismatch usually means the seller registered multiple endpoints without pinning endpoint_id in agentagon.seller / @agentagon/sdk/seller.

Fix:

agentagon endpoints list
# Then in your wrap call:
# wrap(app, ..., endpoint_id="ep_abc123")

503 with Retry-After: 5 from my own seller middleware

The middleware is refusing to serve because no facilitator is configured and AGENTAGON_ALLOW_LOCAL_ONLY is not set. This is the hardened production stance.

Either:

  • Set facilitator_url= (or FACILITATOR_URL env) to a real facilitator
  • For local dev only, set AGENTAGON_ALLOW_LOCAL_ONLY=1 (never in production)

Buyer-side issues

NoCompatibleAcceptError

The seller advertised only schemes / networks your agent doesn’t speak. Check the error’s challenge.accepts to see what the seller offered. Common causes:

  • Seller is Solana-only, agent is Base-only: add a Solana wallet (agentagon agent wallets add --chain solana)
  • Seller advertises upto only: have the seller add exact to its schemes, or run Permit2 approve once

InsufficientBudgetError

The seller’s price exceeded your max_price_usd cap. The exception carries requested_usd and cap_usd. Surface the cap to the user; don’t silently raise it.

MGMT_6014 (PAT daily cap)

You hit the daily spending cap on the buyer PAT. The error includes a recovery block:

{
  "kind": "raise_pat_cap",
  "settings_url": "https://app.agentagon.ai/account/settings",
  "current_cap_usd": "5.00"
}

Either raise the cap in the dashboard, wait until UTC midnight, or use a different PAT.

PaymentRejectedError after the signature was accepted

The signature was valid (the facilitator settled), but the seller returned non-2xx anyway. Check exc.status_code and exc.body. Common causes: the seller hit an internal error after settlement, or the request body changed between probe and retry.

The on-chain settlement is irreversible at this point. If you can prove a refund is owed (the seller’s logs say so), reach out to the seller with the tx_hash.

Treasury issues

balance.stale=true won’t clear

Treasury falls back to its cache when the upstream RPC is unreachable. The flag stays true until the next successful read. Don’t poll faster than once every few seconds; you’ll just keep hitting the same cached row. Watch the seller’s status page.

”I rotated and the old address has my USDC”

That balance is orphaned. The DEK is gone; nothing can sign for the old address again. Always sweep before rotating. See the wallet sweep cookbook.

transfer() returns 403 with transfer_not_permitted_with_capability_cap

Your sub-wallet’s policy includes a capability_cap_usd rule. Transfers carry no capability tag, so the rule can’t bound them; rejecting fail-closed is safer. Use per_tx_cap_usd + daily_cap_usd if you want transfers bounded by dollar limits.

”I lost the api_key after create_treasury”

There’s no recovery flow. The bearer is shown once and never again. You’ll need to claim a new Treasury, or recover via the dashboard’s claim flow if one is set up for your owner type.

CLI issues

agentagon verify fails with well_known_not_found

The seller URL doesn’t host .well-known/agentagon-verification.txt at the expected path. Check the URL is right (no https://www. if you registered without www), confirm your origin actually serves the file, wait a few seconds for CDN cache.

Dashboard handoff doesn’t pick up my agent

agentagon dashboard mints a single-use PAT and opens a URL with #pat=... in the fragment. If the dashboard is loaded behind an auth proxy that strips fragments, the handoff fails. Open the URL directly.

CLI commands time out against my local gate

Set AGENTAGON_API_URL to your local gate:

export AGENTAGON_API_URL=http://localhost:8000
agentagon status

MCP issues

Tools don’t appear in Claude Desktop

Check the MCP server log: Claude Desktop > Settings > Developer > MCP Logs. Common causes:

  • The binary isn’t on PATH: use the absolute path (which agentagon-buyer-mcp)
  • agentagon[mcp] isn’t installed: pip install 'agentagon[mcp]'
  • The env var didn’t propagate: set it in the JSON config’s env block, not in .zshrc

missing_bearer even with env var set

Claude Desktop’s env config only affects the spawned subprocess. If you set AGENTAGON_PAT in your shell profile, it’s not visible to the MCP server. Set it in the JSON config’s env block.

See also

  • docs/EXTERNAL_GAPS.md: upstream gaps that look like our bugs (Permit2 gas, facilitator extensions, etc.)
Facilitators