Troubleshooting
Find the next safe step when setup, approval, or an action does not complete.
Start with the stage that failed. A connection error, an expired approval link, and a policy refusal are different problems and need different responses.
Connection Problems
| Symptom | What to do |
|---|---|
| Your agent cannot find Pakt tools | Confirm the remote server is enabled at https://api.usepakt.ai/mcp. Complete browser sign-in, then start a new agent session. Ask it to list Pakt templates. |
| The installer reports no recognized CLI | It installs the Pakt plugin into supported CLIs already on your machine. Use your MCP client's remote-server settings to add the same URL and sign in. A web-only client is not configured by running a local script. |
| The installer asks you to update your agent | Your installed CLI needs plugin support. Update it, then rerun the installer; do not assume a skipped installation succeeded. |
| Sign-in keeps failing or the session expired | Reconnect through your client's browser sign-in flow. Do not paste a wallet key or seed into the agent. |
| The dashboard and agent show different Pakts | Check that both use the same account and environment. Reconnect the agent to the intended account; a root from another account grants no authority. |
Account Access
You're on the early-access list means access is pending, not that setup failed. Retrying the same tool or reinstalling the connection will not grant access.
Paper trading only lets you draft, review, activate, and disable Pakts and inspect account information. The hosted authorization tools require full access; paper access does not turn a live request into a simulated order.
If the account has full access but Hyperliquid setup is incomplete, return to onboarding. Confirm the restricted execution signer and Hyperliquid agent approvals. A listed active Pakt does not prove that the wallet or venue is ready; those checks also run when an order is proposed.
Drafts and Approvals
| Symptom | What to do |
|---|---|
| A draft will not compile | Ask the agent to correct the named input using the current template and tool schema. Do not remove an intended restriction just to make compilation pass. |
| Your market is unsupported | Ask for current market discovery. Unsupported metadata or non-USDC markets cannot be enabled by changing an allowlist. The current policy program supports venue-forced isolated markets; to replace a legacy Pakt, permanently disable it, wait five minutes, then activate a newly drafted Pakt. User-selected isolated mode on a cross-capable market is unsupported. Every open position on a cross-capable market must use cross mode, even when absent from the order, and each cross-capable market named by the order must have its selected mode set to cross. Closing a position does not reset that market setting. The agent must not route around Pakt. |
| The review link expired | Request a new link for the same final draft. Links last six hours. |
| Approval was interrupted | List your Pakts and check the exact root before requesting another link. Opening a link is not approval. |
| A disabled Pakt cannot be activated | Disable is permanent for that root in the account and environment. Review and approve a replacement with a different root. |
| Both old and new Pakts are active | A replacement does not disable its predecessor. Explicitly disable the old root if it should no longer be usable. |
Execution and Retries
Account proof in progress: another operation for this account is proving or signing. This request did not start. Wait for the active operation, refresh the execution context, and rebuild it. Bundle related Hyperliquid trades rather than submitting them concurrently.
Refused: read the returned reason and compare the proposed action with your approved rules. The current response can be generic and may not identify the failed constraint; do not invent a diagnosis. For example, a $101 opening trade fails a $100 cap, but that is not the only possible check. Keep the receipt ID for investigation. Do not retry unchanged or bypass Pakt.
Signed but no venue result: ask the submitting client whether it sent the request and check the venue. Pakt does not submit orders. A missing dashboard completion is not evidence that nothing executed.
Lost or ambiguous response: keep the original root and exact request. Check the account history and venue before attempting recovery. Do not replace the nonce or deadline merely to obtain another signature; exact reproposal lets the durable backend return the prior result. See the precise retry rules.
Authorization already released / recovery required: stop. Do not request a new signature or submit a replacement. Inspect the receipt and venue state; the original request may already be usable or executed.
A fill is missing from the dashboard: once the client has verified the terminal venue result, it can retry recording that same completion. It must not repeat the trade to repair the display.
Receipt Verification
Open the action and expand Proof and identifiers to find Verify proof in browser. A refused action can have a valid proof.
If verification fails, keep the error and receipt ID. Do not interpret failure as proof that no signature or trade occurred. Receipts from a superseded runtime key cannot be checked against the current signer binding. Check the venue separately and follow the receipt guide.
Information to Keep
For investigation, record the stage, exact error, time, Pakt root, receipt ID, and venue transaction or order reference when available. Share only what is needed through your support channel. Never include access tokens, private keys, seed phrases, or an unsubmitted signed request in a public report.