Troubleshooting

Start with the symptom you're seeing. Each entry says what causes it and how to fix it. For the full list of error codes, see Errors.

A refused payment is never charged. When PowaAgent refuses to sign, nothing leaves your wallet.

Setup#

The Skill doesn't seem to run#

Your agent answers from the web or from memory instead of using PowaAgent.

• Check the Skill is installed: npx skills add powaagent/skills --skill powaagent. It installs into each agent platform it finds on your machine.
• Restart your agent so it loads the Skill.
• Ask for it by name, for example "Use PowaAgent to look up …".

See Install the PowaAgent Skill.

The Skill keeps asking the setup questions#

The Skill asks its setup questions whenever it has no saved configuration and no PowaAgent connector. Common causes:

• You updated the Skill. npx skills update replaces the Skill folder, including skill-config.json. Answer the questions once more.
• Your configuration is from an older version of the Skill. The Skill says so and asks again.

If you've added the PowaAgent connector, the Skill uses it and doesn't need setup. See Skill setup and modes.

"I could not load your PowaAgent API key"#

The Skill is set up for PowaAgent-managed payments but your agent couldn't find your key. It tells you which check failed:

• File not found. The key file isn't at the path you gave in setup. The default is ~/.env.
• No key line. The file exists but has no line for your variable name. Add POWAAGENT_API_KEY=<your key>, or the name you chose.
• File couldn't be read. Your agent may have asked for permission to read the file and been refused. Allow it, or load the variable into your agent's environment.

To move the key to a different file or variable, ask your agent to "Reconfigure PowaAgent".

If you use Claude Code or Claude Desktop, you can skip the key entirely: add the PowaAgent connector in Claude on the web and it's available in both. See Connect an MCP client.

"Your PowaAgent API key was rejected" (401)#

The key is wrong, expired or revoked. The API answers {"message":"Unauthorized"}.

• Keys expire on the date you set when you created them. Check the key under API key in the portal.
• If it has expired or been revoked, revoke any active key, create a new one and replace it in your key file. The portal allows one active key at a time.
• Make sure you copied the whole key with no spaces or quotes.

See API keys.

Connecting#

My assistant can't connect, or shows no PowaAgent tools#

• Use the full server address: https://mcp.powaagent.ai/mcp. A bare mcp.powaagent.ai won't connect.
• If your client reports a redirect error, add a trailing slash: https://mcp.powaagent.ai/mcp/.
• In ChatGPT, set Authentication to OAuth. With "No authentication" the connector can't pay.
• Sign in with your PowaAgent email, password and authenticator code when the sign-in page opens.
• Claude Code or Claude Desktop: you don't need a local MCP setup. Add the connector in Claude on the web, sign in, and it's available in Claude Code and Claude Desktop when you're signed in with the same Claude account.
• Other MCP clients need an API key sent as Authorization: Bearer <key>.

To check that the server is up, open https://mcp.powaagent.ai/healthz. It returns {"status":"ok"}.

See Connect an MCP client.

"Unknown tool"#

The catalog has changed since your assistant loaded its tool list. Ask it to refresh its tools, or reconnect the connector.

Payments refused#

These come from your source policy or your signing access. Nothing was signed and nothing was paid.

"Seller approval pending"#

Your allow list is on and this seller isn't on it. The seller has been added to Pending approvals in the portal.

Approve it there, then ask your agent again. The refused call isn't retried for you.

"Seller deny-listed"#

The seller matches an entry on your deny list. The deny list always wins. Remove the entry under Source policy if you want to allow the seller.

"Ecosystem source not permitted"#

The seller is in a group you've switched off:

• "Open ecosystem source not permitted" means the endpoint is an Open Ecosystem endpoint. Switch on Open Ecosystem under Source policy.
• "Buyer-approved source not permitted" means the seller is a Standard catalog seller. Switch on Buyer Approved endpoints.

See Source trust tiers.

"Spend cap exceeded"#

The payment would go over one of your caps. The message names the cap and gives amounts in USDC base units, where 1,000,000 = $1. For example, Per-call cap exceeded: 15000 > 10000 means a $0.015 payment against a $0.01 per-call cap.

Raise the cap under Source policy, or wait for the 24-hour or 30-day window to move on. The per-call cap starts at $0.10.

"Grant revoked", "Grant expired" or another grant error#

PowaAgent's signing access to your wallet has been revoked or has expired. Renew it on the Agent access tile on the Dashboard, then try again.

If a grant error continues after you've renewed, contact support.

See Delegated Signing grant.

Payments that fail after signing#

"Seller rejected the x402 payment transaction"#

PowaAgent signed the payment but the seller didn't accept it, so nothing was paid. The message gives the seller's reason when there is one. A common reason is that your wallet doesn't hold enough USDC for the payment.

Check your balance and top up on the Funding page. See Fund your wallet.

"The seller doesn't offer USDC on Base"#

PowaAgent pays in USDC on Base only. If a seller accepts only other networks or currencies, it can't be paid through PowaAgent.

The payment may or may not have gone through#

If the connection drops after the payment is sent, the connector reports that the payment is unconfirmed (payment_unconfirmed). It may have settled.

Check Transactions in the portal before you ask again, so you don't pay twice. The Skill tells your agent not to retry these calls on its own.

The seller returned an error#

The service rejected the request, for example because an input wasn't valid or wasn't found.

• Through the connector, you see a seller error with the HTTP status code. The service's own message isn't passed on.
• When your agent calls the API directly, you see the service's own message.

Check what your agent sent and try again. Whether a seller charges for a call that returns an error is up to the seller.

Sandbox#

• "Sandbox unavailable." The service doesn't support the sandbox. The sandbox is available for Premium listings only. Use production, or pick a Premium listing that supports it.
• Test funds refused with a 429. You can request test funds once every 24 hours. Your wallet was already funded within that window, so the call can usually go ahead.
• Test funds refused with a 409. Your wallet hasn't been set up yet. Finish setting up your wallet in the portal first.

See Sandbox testing.

Still stuck#

Email hello@powaagent.ai. To help us find the call, include:

• the time of the call and the service or URL your agent called
• the exact error message
• the transaction hash, if a payment settled