Troubleshooting

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, open the dashboard and select Connect Hyperliquid. If the dashboard asks you to finish account setup, complete the Pakt signer step first. A listed active Pakt does not prove that the wallet or venue is ready; those checks also run when an order is proposed.

If the selected Hyperliquid wallet has less than 20 USDC across its spot and perp account value, deposit USDC or switch to a funded wallet before retrying agent approval. For private beta testing, we recommend a separate account with at least 20 USDC if that is an amount you are comfortable testing with.

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 cross and isolated margin, whether Hyperliquid requires isolated margin or you selected it; to replace a legacy cross-only Pakt, disable it, wait 30 seconds, then activate a newly drafted Pakt. A cross position on a market that Hyperliquid has since made isolated-only blocks every order until you close it on Hyperliquid. 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	Wait 30 seconds after the latest disable in that execution scope, and make sure no other Pakt is active for it; then approve a fresh activation of the same 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. For a Hyperliquid account-condition refusal, the reason can list every evaluated rule result, the authenticated snapshot, earlier still-live signed reservations with their expiry times, and the projection including this order. These are historical values from that decision, not a live account read. An unevaluated pre-state check is not a pass. If the venue snapshot already breaches liquidity, equity or concentration limits, simply shrinking an opening order does not repair that breach. Waiting removes Pakt reservations, not venue-state breaches, and needs a fresh attested snapshot at the reported release second. A changed attempt needs a fresh nonce; no correction guarantees approval. If the reason has only a rule name or generic text, do not invent a diagnosis. Keep the receipt ID. Retrying the same request returns the stored refusal. Do not bypass Pakt.

PolicyStateCapacityExceeded: Pakt's list of signed, still-live orders is full. Reduce-only closes are still approved; other orders wait. The reason gives the first_unreserved_as_of_secs at which the wait ends and at which the earliest reservation is released. Each close signed while the list is full can push the wait later, to at most five minutes after that close.

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.