mmx Errors Cheatsheet

Complete reference of mmx CLI error scenarios and resolutions.

Exit Codes

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

Auth Errors

Scenario	Message
--method api-key without --api-key flag	--api-key is required when using --method api-key.
API key validation failed	API key validation failed.
OAuth timeout (120s)	OAuth callback timed out.
OAuth state mismatch	Invalid OAuth callback.
OAuth token exchange failed	OAuth token exchange failed: ${body}
No credentials on logout	No credentials to clear.
Refresh with api-key mode	Not applicable: not authenticated via OAuth.
Refresh token expired	OAuth session expired and could not be refreshed.

Resolution: Run mmx auth logout && mmx auth login --api-key sk-xxxxx

Text Chat Errors

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

Image Errors

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

Video Errors

Scenario	Message
No --prompt in non-interactive mode	Missing required argument: --prompt
--first-frame not found	First-frame image not found: ${framePath}
--first-frame unreadable	Cannot read image file: ${e.message}
Task Failed	Task Failed: ${status_msg}
Task Unknown	Task Unknown: ${status_msg}
No file_id returned	Task completed but no file_id returned.
No download URL	No download URL available for this file.
Polling timeout	Polling timed out.
Download interrupted	Network request failed.
Disk full	Disk full — cannot write video file.
No --task-id	--task-id is required.
No --file-id	--file-id is required.
No --out	--out is required.

Speech Errors

Scenario	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 no write permission	Permission denied: cannot write to "${outPath}".
Disk full	Disk full — cannot write audio file.

Music Errors

Scenario	Message
Neither --prompt nor --lyrics	At least one of --prompt or --lyrics is required.
--lyrics-file not found	File not found: ${flags.lyricsFile}
--lyrics-file unreadable	Cannot read file: ${e.message}
--out no write permission	Permission denied: cannot write to "${outPath}".
Disk full	Disk full — cannot write audio file.

Vision Errors

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

Search Errors

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

Config Errors

Scenario	Message
--key or --value missing	--key and --value are required.
Invalid config key	Invalid config key "${key}". Valid keys: region, base_url, output, timeout, api_key
Invalid region value	Invalid region "${value}". Valid values: global, cn
Invalid output format	Invalid output format "${value}". Valid values: text, json
Invalid timeout	Invalid timeout "${value}". Must be a positive number.
Unknown command in export-schema	Command "${targetCommand}" not found.

Global Errors (All Commands)

Network Errors

Scenario	Message
Connection failure	Network request failed.
Proxy error	Network request failed. + hint to check HTTP_PROXY/HTTPS_PROXY
Request timeout	Request timed out.
HTTP 408/504	Request timed out (HTTP ${status}).

API Errors

Scenario	Message
HTTP 401/403	API key rejected (HTTP ${status}).
HTTP 429	Rate limit or quota exceeded. ${apiMsg}
Content filter (1002/1039)	Input content flagged by sensitivity filter (${filterType}).
Quota exhausted (1028/1030)	Quota exhausted. ${apiMsg}
Model not on plan (2061)	This model is not available on your current Token Plan. ${apiMsg}
Non-JSON response (e.g. 502)	API returned non-JSON response (${contentType}). Server may be experiencing issues.

File System Errors

Scenario	Message
File not found	File system error: ENOENT: no such file or directory...
Permission denied	File system error: EACCES: permission denied...
Disk full	File system error: ENOSPC: no space left on device...

Config/Credentials File Corruption

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

Quick Fix Reference

Problem	Fix
Auth error	mmx auth logout && mmx auth login --api-key sk-xxxxx
Quota exceeded	mmx quota show to check usage
Network error	Check HTTP_PROXY/HTTPS_PROXY env vars
Content filter	Modify prompt; avoid flagged topics
Timeout	Use --async for videos; increase timeout in config
Model not on plan	Upgrade Token Plan or use default model