> For the complete documentation index, see [llms.txt](/llms.txt). # Troubleshooting Symptom-first fixes for common `mm` CLI issues. ## Start with `mm doctor`[​](#start-with-mm-doctor "Direct link to start-with-mm-doctor") Run `mm doctor` first to inspect CLI version, skill compatibility, authentication, and initialization: ``` mm doctor ``` The output includes `authenticated`, `initialized`, `compatible`, and actionable `hints`. Fix each hint, then re-run `mm doctor` until both `authenticated` and `initialized` are `true`. Authentication and initialization are independent. A session can be authenticated but not initialized, which causes `NOT_INITIALIZED` on wallet commands. ## Authentication and access[​](#authentication-and-access "Direct link to Authentication and access") ### `AUTH_FAILED`, `TOKEN_INVALID`, or `TOKEN_REFRESH_FAILED`[​](#auth%5Ffailed-token%5Finvalid-or-token%5Frefresh%5Ffailed "Direct link to auth_failed-token_invalid-or-token_refresh_failed") Sign in again: ``` mm login browser mm auth status ``` For CI or headless agents: ``` mm login browser --no-wait mm login --token "" ``` ### `ALREADY_AUTHENTICATED`[​](#already%5Fauthenticated "Direct link to already_authenticated") You already have a valid session. Run `mm logout` before signing in again. ### `COMING_SOON` on `mm login qr`[​](#coming%5Fsoon-on-mm-login-qr "Direct link to coming_soon-on-mm-login-qr") QR sign-in is not available in production. Use browser sign-in instead: ``` mm login browser ``` ### `NOT_INITIALIZED`[​](#not%5Finitialized "Direct link to not_initialized") Run setup before wallet commands: ``` mm init mm doctor ``` ### Early Access required[​](#early-access-required "Direct link to Early Access required") If commands fail with authorization errors after sign-in, confirm your account has Early Access at [MetaMask Agent Wallet Early Access](https://metamask.io/agent-wallet). ### Reset local session[​](#reset-local-session "Direct link to Reset local session") ``` mm reset mm login browser mm init --wallet server-wallet --mode guard mm doctor ``` ## Perpetuals[​](#perpetuals "Direct link to Perpetuals") ### `HYPERLIQUID_ERROR` or `ORDER_REJECTED` on first perpetuals trade[​](#hyperliquid%5Ferror-or-order%5Frejected-on-first-perpetuals-trade "Direct link to hyperliquid_error-or-order_rejected-on-first-perpetuals-trade") Deposit USDC from Arbitrum before opening a position: ``` mm perps deposit --venue hyperliquid --amount mm perps balance --venue hyperliquid ``` See [Trade perpetuals](/agent-wallet/guides/trade-perpetuals/). ### Minimum deposit, withdraw, or order notional errors[​](#minimum-deposit-withdraw-or-order-notional-errors "Direct link to Minimum deposit, withdraw, or order notional errors") The CLI provides actionable hints for Hyperliquid minimum-amount failures: - **`MINIMUM_DEPOSIT_AMOUNT`** / **`MINIMUM_WITHDRAW_AMOUNT`**: the error shows the required minimum and your actual amount. Increase the amount and retry. - **`MINIMUM_ORDER_NOTIONAL`**: orders below $10 notional are rejected. Increase your position size or leverage. - **Funding shortfall**: if your venue balance can't cover the order, deposit more USDC or use `--include-spot` to include spot balance. ## Prediction markets[​](#prediction-markets "Direct link to Prediction markets") ### `JsonRpcError: execution reverted` on predict deposit[​](#jsonrpcerror-execution-reverted-on-predict-deposit "Direct link to jsonrpcerror-execution-reverted-on-predict-deposit") Run setup and fund the predict wallet with Polygon USDC.e: ``` mm predict setup --wait mm predict deposit --amount --wait ``` See [Trade prediction markets](/agent-wallet/guides/trade-prediction-markets/). ### `PREDICT_INSUFFICIENT_GAS` on predict deposit[​](#predict%5Finsufficient%5Fgas-on-predict-deposit "Direct link to predict_insufficient_gas-on-predict-deposit") You need native POL on Polygon to cover gas for the predict deposit transaction. Fund your wallet with POL before retrying. ## Swaps[​](#swaps "Direct link to Swaps") ### `NO_QUOTES` or unavailable quote from `mm swap quote`[​](#no%5Fquotes-or-unavailable-quote-from-mm-swap-quote "Direct link to no_quotes-or-unavailable-quote-from-mm-swap-quote") When the bridge returns zero routes for actionable reasons, `mm swap quote` returns a soft unavailable result (exit 0) with a `reason`, `message`, and `hint`. Common reasons include `AMOUNT_TOO_LOW`, `SLIPPAGE_TOO_HIGH`, and `NO_QUOTES`. Adjust the amount, slippage, or token and retry. Do not call `mm swap execute` without a valid `quoteId` from a successful quote step. When bridging with `--refuel`, do not use the flag if the destination token is the destination chain's native gas asset (for example, bridging ETH to Arbitrum ETH). The backend returns no quotes in that case. ### `INSUFFICIENT_FUNDS` or `INSUFFICIENT_GAS` on swap execute[​](#insufficient%5Ffunds-or-insufficient%5Fgas-on-swap-execute "Direct link to insufficient_funds-or-insufficient_gas-on-swap-execute") The CLI runs a preflight check before execution. If you don't have enough of the source token, you receive `INSUFFICIENT_FUNDS` with guidance on the required amount. If native gas balance is too low, the CLI returns `INSUFFICIENT_GAS`. Bridge or transfer the needed tokens before retrying. For gas-insufficient swaps, the CLI may offer a gasless route via the EIP-7702 relay when the quote is gas-included. ### Swap execute fails after a quote[​](#swap-execute-fails-after-a-quote "Direct link to Swap execute fails after a quote") Re-run `mm swap quote` and execute immediately. Quotes expire and are auto-pruned after 24 hours. ## Earn[​](#earn "Direct link to Earn") ### Withdraw reverts on full withdrawal[​](#withdraw-reverts-on-full-withdrawal "Direct link to Withdraw reverts on full withdrawal") For rebasing tokens (like Aave aTokens), interest accrues between the balance query and transaction execution. The CLI applies a small dust buffer for `--amount all` withdrawals, but if the transaction still reverts, it automatically retries up to 3 times. If retries fail, try withdrawing a slightly smaller amount. ### Position not showing after supply[​](#position-not-showing-after-supply "Direct link to Position not showing after supply") Earn positions can lag 15–30 seconds after deposit. Use `--wait` on `mm earn supply` to poll until the position reflects (up to ~45 seconds), or check manually: ``` mm earn positions --chain ``` ### Approval required for supply[​](#approval-required-for-supply "Direct link to Approval required for supply") When supplying for the first time, the CLI sends an ERC-20 approval transaction before the supply. In server-wallet mode with Guard Mode, this may require 2FA approval. ## Transfers[​](#transfers "Direct link to Transfers") ### Insufficient balance on the target chain[​](#insufficient-balance-on-the-target-chain "Direct link to Insufficient balance on the target chain") `mm transfer` only spends balances on the chain specified by `--chain-id`. Bridge tokens with `mm swap execute` first. ### ENS names not resolving[​](#ens-names-not-resolving "Direct link to ENS names not resolving") ENS is not supported for `--to`. Use a hex address. ## Server-wallet polling[​](#server-wallet-polling "Direct link to Server-wallet polling") ### Command returned a `pollingId` but no hash[​](#command-returned-a-pollingid-but-no-hash "Direct link to command-returned-a-pollingid-but-no-hash") Use `--wait` on signing and transfer commands, or watch the job: ``` mm wallet requests watch --polling-id ``` The default wallet job poll timeout is 10 minutes. You can override it with `--wallet-timeout`(max 600 seconds). See [Architecture](/agent-wallet/reference/architecture/). ## 2FA approval pending[​](#2fa-approval-pending "Direct link to 2FA approval pending") If a job status is `AWAITING_MFA`, approve or reject the transaction through the channel for your sign-in method: MetaMask Mobile push (QR sign-in) or the email approval link (browser sign-in). ## Related pages[​](#related-pages "Direct link to Related pages") - [Error codes](/agent-wallet/reference/error-codes/) - [Commands reference](/agent-wallet/reference/commands/)