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