Troubleshooting
| What you see | What to do |
|---|---|
| "AETHERWAVE_API_KEY environment variable is required" | The client is not passing the key. Check the env block, then fully restart the client |
| 401, invalid API key | The key was revoked or replaced. Create a new one under Profile, then Developer |
| 402, insufficient credits | Check aetherwave_balance and top up at https://aetherwavestudio.com/buy-credits |
A tool answered state: "running" |
Normal for long jobs. Follow it with aetherwave_get_job; do not resubmit. See Long jobs |
| The chat said the call timed out | The job kept running. Use aetherwave_get_job with the task ID, or find it in your gallery |
| "Unprocessable Entity" on a reframe | The source link has spaces or brackets. Use a clean gallery link |
Comic status says drawing: "stalled" |
Call aetherwave_comic_draw again; it only draws what is missing |
| A comic panel keeps being refused | Reword it with aetherwave_comic_redraw_panel and a new prompt |
| A video character has a different face in each clip | Use referenceImages, not imageUrl, and copy the identity block word for word. See Your characters in video |
| The Printful tools are missing | They only appear on the npm package with PRINTFUL_API_TOKEN set |
Known gaps
- Mastering has no task ID. A master that outlives the call can only be found in the gallery. A server change to give it one is planned.
- Upscale video reaches 2K. 4K and 8K exist on the website and are coming to the MCP in 0.3.1.
- Suno V6 is on the website but not yet in the MCP's model list (the MCP tops out at V5.5).
- Some tool descriptions in 0.3.0 quote older prices or retired models (image upscale factors, a few image and video model names). The prices in the tools reference are the live ones; the descriptions are corrected in 0.3.1.
- Soul Forge band creation stays on the website only.
For anything else, the full AetherWave MCP User Manual (PDF) covers every tool.