Rendering failed

When a render fails, the Queue tab shows the error message on the row for that render attempt. A failed attempt does not produce a Library card, so you can safely retry from Create without worrying about duplicate entries.

If the failure message isn’t recognized, the row shows a Show details link — click it to reveal the raw error text from the backend, which is usually enough to search for the underlying cause.

Common causes

”Renderer exited with code 1”

Something in the render pipeline failed. Usually one of:

• The MP3 is corrupted or an unusual format.
• Not enough free disk space (need ~500 MB per song).
• A font specified in Settings isn’t installed.

Try: re-render with --verbose logs via Settings → Advanced → Show developer log and look for the render error.

”Background fetch failed”

The background image service returned an error.

Try:

1. Check your internet connection.
2. Wait a minute and retry — the service occasionally rate-limits. The app already retries automatically with backoff.
3. Go back to Create and click Generate again — a failed render leaves no Library card behind, and a fresh render attempt will re-fetch any missing backgrounds.

”Background generation failed: No module named ‘diffusers’”

The SDXL-Lightning generator is active but its Python runtime (diffusers / transformers) wasn’t bundled with this build of the app. Every background request will fail instantly.

Fix:

1. Update the app to a build that includes the local-diffusion runtime — from that point on, Settings → Background Generator shows the SDXL card normally and generation works.
2. Or, as an immediate workaround, go to Settings → Background Generator and pick Pollinations.ai instead. Renders will resume.
3. If the SDXL card already shows a Not available in this build notice, the app has detected this and will not let you activate or download it — pick Pollinations (or None + upload your own).

”Transcription failed”

The lyric-timing model had trouble with the audio.

Try:

• If the audio is very low quality or has a lot of background noise, transcription may struggle. Use a higher-quality source MP3.
• Clear working files — either delete tmp/ under the app data directory, or use App menu → Clear Renders… which also removes tmp/. Then render again.

”Not enough disk space” in the download bar

If the download bar (bottom-left of any tab) shows “Not enough disk space”, the rendering engine installer could not save ffmpeg or ffprobe to disk — not the render itself.

Fix:

1. Free up at least 200 MB of disk space (the two binaries together are about 100 MB; the installer needs headroom).
2. Click Retry in the download bar.
3. No reinstall is needed — just freeing space and retrying is enough.

”Out of memory”

Rendering needs ~2 GB of RAM peak. On low-memory machines this can fail.

Try:

• Close other apps.
• Restart the computer and try again.
• Shorter songs (< 5 min) use less memory.

Still stuck?

1. Go to Settings → Advanced → Show developer log.
2. Reproduce the error.
3. Copy the log and open an issue.