mudler/LocalAI · error · RuntimeError

create_sample failed: {sample_result.error or sample_result.

Error message

create_sample failed: {sample_result.error or sample_result.status_message}

What it means

Raised by the ace-step music backend when the LLM lyric/metadata step fails: create_sample(...) (invoked when an LLM handler is configured) returns a result whose success flag is false, and the RuntimeError interpolates sample_result.error or sample_result.status_message (whichever is set; if both are empty the message ends with an empty tail). This aborts the generation before audio synthesis, since caption/lyrics/bpm/keyscale/timesignature come from that call.

Source

Thrown at backend/python/ace-step/backend.py:169

        parsed_language = None
        if sample_query:
            for hint in ("english", "en", "chinese", "zh", "japanese", "ja"):
                if hint in sample_query.lower():
                    parsed_language = "en" if hint == "english" or hint == "en" else hint
                    break
        vocal_lang = vocal_language if vocal_language and vocal_language != "unknown" else parsed_language
        sample_result = create_sample(
            llm_handler=llm_handler,
            query=sample_query or "NO USER INPUT",
            instrumental=instrumental,
            vocal_language=vocal_lang,
            temperature=lm_temperature,
            top_k=lm_top_k,
            top_p=lm_top_p,
            use_constrained_decoding=True,
        )
        if not sample_result.success:
            raise RuntimeError(f"create_sample failed: {sample_result.error or sample_result.status_message}")
        caption = sample_result.caption or caption
        lyrics = sample_result.lyrics or lyrics
        bpm = sample_result.bpm
        key_scale = sample_result.keyscale or key_scale
        time_signature = sample_result.timesignature or time_signature
        if sample_result.duration is not None:
            audio_duration = sample_result.duration
        if getattr(sample_result, "language", None):
            vocal_language = sample_result.language

    if use_format and (caption or lyrics) and llm_handler and getattr(llm_handler, "llm_initialized", False):
        user_metadata = {}
        if bpm is not None:
            user_metadata["bpm"] = bpm
        if audio_duration is not None and float(audio_duration) > 0:
            user_metadata["duration"] = int(audio_duration)
        if key_scale:
            user_metadata["keyscale"] = key_scale

View on GitHub (pinned to 44413a9d06)

Solutions

Check the LocalAI logs for the underlying sample_result.error / status_message text — it names the real cause
Verify the configured LLM is up (the same handler the ace-step backend uses) and retry
If the LLM is flaky, supply caption/lyrics inputs directly so create_sample is skipped or its outputs are replaced
Lower lm_temperature / adjust top_k/top_p if constrained decoding output is malformed

Example fix

# before
if not sample_result.success:
    raise RuntimeError(f"create_sample failed: {sample_result.error or sample_result.status_message}")

# after: guarantee a non-empty reason
if not sample_result.success:
    reason = sample_result.error or sample_result.status_message or 'no error reported'
    raise RuntimeError(f"create_sample failed: {reason}")

Defensive patterns

Strategy: fallback

Validate before calling

# Skip the LLM sample step entirely when inputs are already supplied
should_call_llm = llm_handler is not None and getattr(llm_handler, 'llm_initialized', False) and (caption is None or lyrics is None)
if should_call_llm:
    sample_result = create_sample(...)
    ...
else:
    caption = caption or ''
    lyrics = lyrics or ''

Type guard

def sample_result_failed(sample_result) -> bool:
    return not getattr(sample_result, 'success', False)


def sample_failure_reason(sample_result) -> str:
    return (sample_result.error
            or getattr(sample_result, 'status_message', None)
            or 'no error reported')

Try / catch

try:
    run_ace_step_generation(...)
except RuntimeError as err:
    if 'create_sample failed' in str(err):
        # LLM metadata step failed: fall back to user-supplied caption/lyrics or re-raise
        if caption and lyrics:
            logging.warning('%s; continuing with user-supplied caption/lyrics', err)
        else:
            raise
    else:
        raise

Prevention

Pass caption/lyrics/bpm/key_scale/time_signature explicitly so generation works even when the LLM is down
Health-check the configured LLM handler before starting a music generation job
Log sample_result.error and status_message both — one is sometimes empty
Pin a helper LLM that reliably satisfies the constrained-decoding schema

When it happens

Trigger: Calling ace-step generation with lyrics_mode/sample generation enabled while the configured LLM endpoint is unreachable, times out, returns invalid JSON, or violates constrained decoding (use_constrained_decoding=True) so create_sample marks the result failed.

Common situations: LLM_API_KEY missing or model not loaded; the helper LLM too small to honor the constrained JSON schema; network egress blocked from the backend container; temperature/top_k/top_p values causing degenerate output that fails parsing.

Related errors

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/0ba0281c4bd2acbc. Report an issue: GitHub.