ERRORS.md

MiniMax CLI Error Reference

This document lists all error scenarios and the messages users will see.

Auth Commands

mmx auth login

Scenario	Error Message
--method api-key without --api-key	--api-key is required when using --method api-key.
API key validation failed	API key validation failed.
OAuth callback timeout (120s)	OAuth callback timed out.
OAuth state mismatch	Invalid OAuth callback.
OAuth error in callback	OAuth error: ${error}
OAuth token exchange failed	OAuth token exchange failed: ${body}
MINIMAX_API_KEY already set (non-interactive)	Warning: MINIMAX_API_KEY is already set in environment.
No credentials found (non-interactive)	No credentials found. + the searched config.json path and hint: Log in: mmx auth login, --api-key sk-xxxxx, or MMX_CONFIG_DIR=/path/to/.mmx

mmx auth logout

Scenario	Error Message
No credentials to clear	No credentials to clear.

mmx auth refresh

Scenario	Error Message
No OAuth credentials (api-key mode)	Not applicable: not authenticated via OAuth.
Refresh token expired	OAuth session expired and could not be refreshed.

mmx auth status

Scenario	Error Message
No credentials	authenticated: false + Not authenticated.
Quota request failed	Failed to fetch quota: ${err.message}

---

Text Commands

mmx text chat

Scenario	Error Message
No --message in non-interactive mode	Missing required argument: --message
--messages-file file not found	File not found: ${filePath}
--messages-file content is not valid JSON	--messages-file content is not valid JSON.
--tool not valid JSON (not a file path)	--tool argument "${t}" is not valid JSON.
--tool file not found	Tool definition file not found: ${t}
--tool file exists but invalid JSON	Tool definition file "${t}" contains invalid JSON.
Stream disconnected mid-response	Stream disconnected before response completed.

---

Image Commands

mmx image generate

Scenario	Error Message
No --prompt in non-interactive mode	Missing required argument: --prompt
--subject-ref local image not found	Subject reference image not found: ${params.image}
--subject-ref image unreadable	Cannot read image file: ${e.message}
--out-dir no write permission	Permission denied: cannot create directory "${outDir}".
--out-dir other error	Cannot create directory "${outDir}": ${e.message}
success_count === 0 (all rejected)	Image generation failed: all images were rejected (content policy or model error).

---

Video Commands

mmx video generate

Scenario	Error Message
No --prompt in non-interactive mode	Missing required argument: --prompt
--first-frame file not found	First-frame image not found: ${framePath}
--first-frame file unreadable	Cannot read image file: ${e.message}
Task status Failed	Task Failed: ${status_msg} (when base_resp.status_code is 0 or absent); otherwise API Errors apply
Task status Unknown	Task Unknown: ${status_msg} (when base_resp.status_code is 0 or absent); otherwise API Errors apply
Success but no file_id	Task completed but no file_id returned.
file_id has no download_url	No download URL available for this file.
Polling timeout	Polling timed out.
Download network interrupted	Network request failed.
Disk full	Disk full — cannot write video file.
--download path no write permission	Cannot write file: ${e.message}

mmx video task get

Scenario	Error Message
No --task-id	--task-id is required.

mmx video download

Scenario	Error Message
No --file-id	--file-id is required.
No --out	--out is required.
download_url is empty	No download URL available for this file.
Download failed (HTTP error)	Download failed: HTTP ${res.status}
Disk full	Disk full — cannot write video file.
Output path no write permission	Cannot write file: ${e.message}

---

Speech Commands

mmx speech synthesize

Scenario	Error Message
No --text and no --text-file	--text or --text-file is required.
--text-file not found	File not found: ${flags.textFile}
--text-file unreadable	Cannot read file: ${e.message}
--out path no write permission	Permission denied: cannot write to "${outPath}".
Disk full	Disk full — cannot write audio file.

mmx speech transcribe

Scenario	Error Message
No --file (and no positional path) in non-interactive mode	Missing required argument: --file
Audio file not found	File not found: ${fullPath}
Invalid --response-format	Invalid response format "${fmt}". Supported: json, verbose_json, srt, vtt
Audio file above 50 MB	Audio file is ${size} MB; speech-to-text allows at most 50 MB: ${fullPath}
Server rejects the upload as too large (HTTP 413)	Audio file exceeds the speech-to-text size limit (HTTP 413). ${message}
Audio flagged by the sensitivity filter (HTTP 422)	Input audio flagged by sensitivity filter (${message})
--stream with a response format other than json	response_format "${fmt}" cannot be combined with stream=true; streaming returns incremental json only.
--stream together with --out	--stream and --out cannot be combined.
--out unwritable (permissions, missing directory)	File system error: ${message}
Disk full	Disk full — cannot write transcript file.

Audio longer than 500 seconds and unsupported/corrupt audio are rejected by the API; the server message is surfaced verbatim (e.g. API error: invalid params, ... (HTTP 400)).

mmx speech voices

All errors fall under Network Errors.

---

Vision Commands

mmx vision describe

Scenario	Error Message
Neither --image nor --file-id in non-interactive mode	Missing required argument. Must provide either --image or --file-id.
Both --image and --file-id provided	Conflicting arguments: cannot provide both --image and --file-id.
Local image file not found	File not found: ${image}
Image format not supported	Unsupported image format "${ext}". Supported: jpg, jpeg, png, webp
Remote image URL download failed	Failed to download image: HTTP ${res.status}

---

Search Commands

mmx search query

Scenario	Error Message
No --q in non-interactive mode	--q is required.

---

Quota Commands

mmx quota show

All errors fall under Network Errors.

---

Config Commands

mmx config set

Scenario	Error Message
--key or --value missing	--key and --value are required.
key not in valid list	Invalid config key "${key}". Valid keys: region, base_url, output, timeout, api_key
region value invalid	Invalid region "${value}". Valid values: global, cn
output value invalid	Invalid output format "${value}". Valid values: text, json
timeout not a positive number	Invalid timeout "${value}". Must be a positive number.

mmx config export-schema

Scenario	Error Message
--command specifies non-existent command	Command "${targetCommand}" not found.

---

Update Commands

mmx update

No error scenarios — prints a message directing users to run npm update -g mmx-cli manually.

---

File Commands

mmx file upload

Scenario	Error Message
--file local file not found	File not found: ${fullPath}
API error (size limit, unsupported type, etc.)	API Errors apply

mmx file delete

Scenario	Error Message
No --file-id in non-interactive mode	Missing required argument: --file-id

mmx file list

Scenario	Error Message
All errors fall under Network Errors

---

Global Errors (All Commands)

Network Errors

Scenario	Error Message
Network/connection failure	Network request failed. + hint: Check your network connection and proxy settings.
Proxy error detected	Network request failed. + hint: Proxy error — check HTTP_PROXY / HTTPS_PROXY environment variables and proxy authentication.
Request timeout (AbortSignal)	Request timed out.
HTTP 408 / 504	Request timed out (HTTP ${status}).

API Errors

Scenario	Error Message
HTTP 401 / 403	API key rejected (HTTP ${status}).
HTTP 429	Rate limit or quota exceeded. ${apiMsg}
status_code 1002 / 1039 (content filter)	Input content flagged by sensitivity filter (${filterType}).
status_msg contains "new_sensitive" / output sensitivity (HTTP 200)	Output withheld by content moderation (${apiMsg}).
status_code 1028 / 1030 (quota exhausted)	Quota exhausted. ${apiMsg}
status_code 2061 (model not on plan)	This model is not available on your current Token Plan. ${apiMsg}
Other API errors	API error: ${apiMsg} (HTTP ${status})
Non-JSON response body (e.g., gateway 502)	API returned non-JSON response (${contentType}). Server may be experiencing issues.

File System Errors

Scenario	Error Message
File not found	File system error: ENOENT: no such file or directory... + hint
Permission denied	File system error: EACCES: permission denied... + hint
Disk full	File system error: ENOSPC: no space left on device... + hint
Other FS errors	File system error: ${err.message} + hint

Process Signals

Scenario	Error Message
Ctrl+C / SIGINT	Interrupted. Exiting. (exit code 130)

Config / Credentials File Corruption

Scenario	Behavior
~/.mmx/credentials.json corrupted	Warning written to stderr; treated as no credentials
~/.mmx/config.json corrupted	Warning written to stderr; treated as empty config

Exit Codes

Code	Meaning
0	Success
1	General error
2	Usage error (invalid arguments)
3	Authentication error
4	Quota error
5	Timeout
6	Network error
10	Content filter
130	Interrupted (Ctrl+C / SIGINT)