> 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. The CLI detects native POL shortfalls from both SDK preflight checks and RPC errors, and surfaces this code with a POL-specific hint instead of a generic `PREDICT_ERROR`. Fund your wallet with POL, verify with `mm wallet balance`, then retry. ### `PREDICT_ORDER_SIZE_TOO_SMALL` on predict place[​](#predict%5Forder%5Fsize%5Ftoo%5Fsmall-on-predict-place "Direct link to predict_order_size_too_small-on-predict-place") The order size is below the exchange minimum. Raise `--size` to at least the minimum stated in the error hint, and inspect liquidity with `mm predict book` before retrying. ### `PREDICT_ORDER_NOT_FILLED` on predict place[​](#predict%5Forder%5Fnot%5Ffilled-on-predict-place "Direct link to predict_order_not_filled-on-predict-place") A fill-or-kill (FOK) order could not be fully filled at the requested price. Adjust `--size` or `--price`, check liquidity with `mm predict book`, or use a GTC (good-till-cancelled) order type instead of FOK. ## 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/)