# Error Handling (MiniMax-Specific)

The base skill's [`error-handling.md`](../../music-craft/references/error-handling.md) covers generic failures. This file covers MiniMax-specific failure modes, especially for the advanced features (cover, mashup, emotion analysis, lyrics generation API).

## mmx CLI Errors

| Error | Cause | Fix |
|---|---|---|
| `mmx: command not found` | CLI not installed | Install via the MiniMax install guide, or skip mmx-specific features |
| `401 Unauthorized` | Bad or expired API key | `mmx auth login --api-key "$MINIMAX_API_KEY"` |
| `403 Forbidden` | API key does not have the required plan | Upgrade to a Token Plan that includes the feature |
| `429 Too Many Requests` | RPM or Token Plan quota exceeded | Wait 60s; check Token Plan usage; reduce concurrency |
| `Region mismatch` | CLI default region is wrong | `mmx config set --key region --value global` |
| `Network error` | Connectivity issue | Check internet, retry with `--retry 3` |
| `Invalid prompt` | Prompt has forbidden content | Check for copyrighted lyrics, hate speech, etc. |
| `Lyrics too long` | > 3500 chars | Shorten or split into sections |
| `Audio file too large` | > 50 MB | Convert with `ffmpeg -b:a 128k` to lower bitrate |
| `Audio file too long` | > 6 minutes | Trim with `ffmpeg -t 360` |

## Cover Workflow Errors

| Error | Cause | Fix |
|---|---|---|
| `audio_url unreachable` | URL is dead, requires auth, or blocked | Download with `yt-dlp` or `curl` first, then use `--audio-file` |
| `cover_feature_id expired` | > 24 hours since preprocess | Re-run preprocess |
| `cover_feature_id invalid` | ID was mistyped or not from this API key | Re-run preprocess, copy ID carefully |
| ASR extracted wrong lyrics | Noisy audio, accented vocals, non-English | Use two-step with manually-edited lyrics |
| Output melody is unrecognisable | Style transfer too aggressive | Reduce the prompt's style intensity, or use a less dramatic target style |
| Output is sparse | Anti-sparse rules not applied | Add explicit instruments and "ALL instruments ALWAYS playing" |
| Output is the same as the input | Style transfer did not apply | Check the prompt; make style descriptors more specific |
| Output has vocals when instrumental was requested | `--instrumental` flag was not set, or model does not support the language | Set `--instrumental` and try again |
| Output duration is wrong (too short, e.g. 30-60s when you wanted 3:30) | MiniMax has no native duration control | Length is driven by **lyrics length** (primary) + **structure tags** (secondary) + **prompt hints** (tertiary). For a 3:30 song you need ~150-200 lyrics words with full song structure (`[Verse 1]`/`[Pre-Chorus]`/`[Chorus]`/`[Verse 2]`/`[Bridge]`/`[Outro]`). Add prompt hints like "3 minute song" or use `--structure "intro-verse-pre_chorus-chorus-verse-chorus-bridge-chorus-outro"`. If you need precise length, switch to `music-craft`'s ACE-Step backend which has `audio_duration`. |
| Output duration is wrong (too long, e.g. 5+ min when you wanted 3:30) | Lyrics are too long, or model is filling sections slowly | Trim lyrics to ~120 words, add explicit `[Instrumental Break]` tags to control pacing, or remove the bridge section. |

## Lyrics Generation API Errors

| Error | Cause | Fix |
|---|---|---|
| `mode is required` | Missing `mode` in request body | Add `"mode": "write_full_song"` or `"edit"` |
| `prompt is required` | Missing `prompt` | Add the theme/style instruction |
| `lyrics is required for edit mode` | `edit` mode without `lyrics` field | Add existing lyrics to edit |
| `lyrics too long` | > 3500 chars | Shorten or split |
| `prompt too long` | > 2000 chars | Shorten |
| Output is in wrong language | Prompt did not specify language | Add language: "in French", "en español", "auf Deutsch" |
| Output is too short | Prompt was vague | Add: "with at least 3 verses, 2 choruses, and a bridge" |
| Output is too long | Prompt asked for too much | Add: "concise, 2 verses and 1 chorus" |
| Output is AI-generic | Prompt was generic | Add specific imagery: "mention a specific place, time of day, object" |
| Edit mode did not modify enough | Prompt was not specific about what to change | Be explicit: "make the chorus stronger", "add a bridge about X" |

## Emotion Analysis Errors

| Error | Cause | Fix |
|---|---|---|
| `librosa.load fails` | Unsupported format | Convert via `ffmpeg -i input.m4a output.wav` |
| `No pitch detected` | Instrumental only | Skip emotion analysis, use basic features only |
| `Very short audio` | < 5 seconds | Skip emotion analysis, warn the user |
| `Too quiet / clipping` | Bad levels | Normalize: `ffmpeg -i input.wav -af loudnorm output.wav` |
| `parselmouth not installed` | Optional dep missing | `pip install praat-parselmouth` (better pitch tracking) |
| `allin1 not installed` | Optional dep missing | `pip install allin1` (neural structure segmentation) |
| Analysis takes too long | Very long audio or many sections | Trim to a representative 3–4 minute segment |
| Output JSON is incomplete | Process killed or error mid-run | Run with `--verbose` to see the error, fix and retry |

## Mashup Workflow Errors

| Error | Cause | Fix |
|---|---|---|
| `Song A audio download failed` | YouTube bot detection or dead URL | Update yt-dlp (`pip install -U yt-dlp`), or get the file from the user |
| `Song B style unknown` | LLM does not have training data for Song B | Ask the user for a 2–3 sentence description of Song B's style |
| `Cover preserved wrong melody` | ASR extracted wrong lyrics, the model anchored on the wrong phrases | Use two-step with manually-edited lyrics |
| `Output is sparse` | Anti-sparse rules not applied for the unusual combination | Add explicit anti-sparse text, list every instrument |
| `Output is too long` | Combined content is too rich | Trim the lyrics, drop a verse or chorus |
| `Emotion analysis contradicted by Song B style` | Song A is melancholic, Song B is upbeat | Embrace the tension or adjust one of them; this is a creative call |

## Retry Adjustment Rules

Use one focused retry before widening the workflow. Change the smallest thing that addresses the failure:

| Failure | First retry adjustment | If it still fails |
|---|---|---|
| Cover loses melody | Switch to two-step, add `preserve the original melody contour`, remove half the style adjectives, and keep the original lyric line breaks | Lower the target intensity and simplify the style to fewer descriptors |
| ASR lyrics are wrong | Re-run as two-step and replace ASR text with manually corrected lyrics or a user transcript; add the source language explicitly | Ask the user for the exact lines or fall back to translated/new lyrics |
| Mashup is incoherent | Keep Song A lyrics/structure fixed, reduce Song B to 3-5 style descriptors, and make Song B style secondary to Song A content | Fall back to standard generation with a single combined prompt |
| Emotion is too flat | Add section contrast, `[Break]` and `[Build Up]` tags, and stronger dynamic words for chorus/bridge changes | Narrow to one dominant emotion and drop weak secondary emotions |
| `mmx` flags conflict | Make flags the source of truth for BPM/key/structure and remove the same values from the prompt | Keep only the mandatory flags and shorten the prompt to feel-only language |
| YouTube/download is blocked | Retry once with updated `yt-dlp` and a direct URL if the user has one | Ask for a local audio file or switch to a prompt-only base-skill workflow |

## Token Plan 3.0 Specific Issues

Under Token Plan 3.0 (June 2026+), the quota is credit-based. Common issues:

| Symptom | Cause | Fix |
|---|---|---|
| 429 errors with no clear pattern | Token Plan 5h window exhausted | Wait for the 5h reset, or upgrade plan |
| All calls fail with auth error | API key revoked or expired | Regenerate API key in MiniMax dashboard |
| Output quality degrades over time | Quota running low, model degrades to cheaper path | Check Token Plan usage, upgrade if needed |
| Weekly cap hit (rare on Plus) | Weekly window exhausted | Wait for Monday 02:00 CEST reset |

To check current Token Plan usage:

```bash
curl -s -H "Authorization: Bearer $MINIMAX_API_KEY" \
  https://www.minimax.io/v1/token_plan/remains | jq .
```

## Sparse / A Cappella Output (MiniMax-Specific)

MiniMax is more aggressive than other providers in interpreting "sparse" as "remove all instruments". Special fix path:

1. **Add the canonical anti-sparse text** to the prompt:
   ```
   ALL instruments ALWAYS playing throughout the entire song, NEVER go a cappella or silent at any point
   ```

2. **List every instrument** you want to hear, even if they are obvious:
   ```
   accordion, upright bass, orchestral strings, piano, light percussion
   ```
   Do not say "with strings" — say "orchestral strings (violin, viola, cello)".

3. **Add explicit treatment of quiet sections**:
   ```
   quiet sections: reduced to accordion and bass only, still fully played, NOT silent
   ```

4. **Use `--avoid` with the canonical list**:
   ```
   sparse, a cappella, minimal arrangement, electronic sounds, synthetic textures
   ```

5. **If still sparse after one retry**, switch to a different style. The combination of style + prompt may be incompatible.

6. **Never** use these phrases alone in a MiniMax prompt:
   - `sparse arrangement`
   - `minimal instrumentation`
   - `stripped back`
   - `a cappella section`
   - `quiet and sparse`
   - `minimal but present`

   If the user asks for any of these, translate into the explicit-instrument form.

## When to Give Up and Ask the User

If after 2 retries the result is still unacceptable:

1. Show the user the best attempt so far.
2. Explain what was tried and why it failed.
3. Ask the user for:
   - A clearer direction (specific style, reference artist, sample audio)
   - Permission to try a different model (`music-2.6` vs `music-2.6-free`)
   - Permission to switch to standard generation instead of cover (for mashups)
   - Acceptance of the best result with a note about the limitation

Never loop forever. Always give the user an off-ramp.

## When to Fall Back to the Base Skill

If the MiniMax-specific features are causing problems, fall back to `music-craft`:

- Cover is failing → use standard generation with the style as a reference (no melody preservation)
- Mashup is failing → use standard generation with a combined prompt
- Emotion analysis is failing → skip it, build the prompt from LLM knowledge of the songs
- mmx CLI is unavailable → use the `music_generate` tool with prompt-only

The base skill is the safety net for the advanced features.