For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Troubleshooting

Symptom-first fixes for common mm CLI issues.

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​

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 "<cliToken:cliRefreshToken>"

ALREADY_AUTHENTICATED​

You already have a valid session. Run mm logout before signing in again.

COMING_SOON on mm login qr​

QR sign-in is not available in production. Use browser sign-in instead:

mm login browser

NOT_INITIALIZED​

Run setup before wallet commands:

mm init
mm doctor

Early Access required​

If commands fail with authorization errors after sign-in, confirm your account has Early Access at MetaMask Agent Wallet Early Access.

Reset local session​

mm reset
mm login browser
mm init --wallet server-wallet --mode guard
mm doctor

Perpetuals​

HYPERLIQUID_ERROR or ORDER_REJECTED on first perpetuals trade​

Deposit USDC from Arbitrum before opening a position:

mm perps deposit --venue hyperliquid --amount <AMOUNT>
mm perps balance --venue hyperliquid

See Trade perpetuals.

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​

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 <AMOUNT> --wait

See Trade prediction markets.

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​

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​

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​

Re-run mm swap quote and execute immediately. Quotes expire and are auto-pruned after 24 hours.

Earn​

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​

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 <CHAIN_ID>

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​

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 is not supported for --to. Use a hex address.

Server-wallet polling​

Command returned a pollingId but no hash​

Use --wait on signing and transfer commands, or watch the job:

mm wallet requests watch --polling-id <POLLING_ID>

The default wallet job poll timeout is 10 minutes. You can override it with --wallet-timeout (max 600 seconds).

See Architecture.

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).

On this page