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 |
| A reframe fails before it starts | The source must be a public https link. Upload the file with aetherwave_upload_to_gallery and use the link it returns |
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.
- Video reframe is temporarily unavailable. Its provider removed the model on 2026-11-11.
aetherwave_reframe_videois refused before it starts and nothing is charged. Image reframe works. - 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.