{"record":{"id":"0ba0281c4bd2acbc","repo":"mudler/LocalAI","slug":"create-sample-failed-sample-result-error-or-samp","errorCode":null,"errorMessage":"create_sample failed: {sample_result.error or sample_result.status_message}","messagePattern":"create_sample failed: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/python/ace-step/backend.py","lineNumber":169,"sourceCode":"        parsed_language = None\n        if sample_query:\n            for hint in (\"english\", \"en\", \"chinese\", \"zh\", \"japanese\", \"ja\"):\n                if hint in sample_query.lower():\n                    parsed_language = \"en\" if hint == \"english\" or hint == \"en\" else hint\n                    break\n        vocal_lang = vocal_language if vocal_language and vocal_language != \"unknown\" else parsed_language\n        sample_result = create_sample(\n            llm_handler=llm_handler,\n            query=sample_query or \"NO USER INPUT\",\n            instrumental=instrumental,\n            vocal_language=vocal_lang,\n            temperature=lm_temperature,\n            top_k=lm_top_k,\n            top_p=lm_top_p,\n            use_constrained_decoding=True,\n        )\n        if not sample_result.success:\n            raise RuntimeError(f\"create_sample failed: {sample_result.error or sample_result.status_message}\")\n        caption = sample_result.caption or caption\n        lyrics = sample_result.lyrics or lyrics\n        bpm = sample_result.bpm\n        key_scale = sample_result.keyscale or key_scale\n        time_signature = sample_result.timesignature or time_signature\n        if sample_result.duration is not None:\n            audio_duration = sample_result.duration\n        if getattr(sample_result, \"language\", None):\n            vocal_language = sample_result.language\n\n    if use_format and (caption or lyrics) and llm_handler and getattr(llm_handler, \"llm_initialized\", False):\n        user_metadata = {}\n        if bpm is not None:\n            user_metadata[\"bpm\"] = bpm\n        if audio_duration is not None and float(audio_duration) > 0:\n            user_metadata[\"duration\"] = int(audio_duration)\n        if key_scale:\n            user_metadata[\"keyscale\"] = key_scale","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/ace-step/backend.py#L151-L187","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nif not sample_result.success:\n    raise RuntimeError(f\"create_sample failed: {sample_result.error or sample_result.status_message}\")\n\n# after: guarantee a non-empty reason\nif not sample_result.success:\n    reason = sample_result.error or sample_result.status_message or 'no error reported'\n    raise RuntimeError(f\"create_sample failed: {reason}\")","handlingStrategy":"fallback","validationCode":"# Skip the LLM sample step entirely when inputs are already supplied\nshould_call_llm = llm_handler is not None and getattr(llm_handler, 'llm_initialized', False) and (caption is None or lyrics is None)\nif should_call_llm:\n    sample_result = create_sample(...)\n    ...\nelse:\n    caption = caption or ''\n    lyrics = lyrics or ''","typeGuard":"def sample_result_failed(sample_result) -> bool:\n    return not getattr(sample_result, 'success', False)\n\n\ndef sample_failure_reason(sample_result) -> str:\n    return (sample_result.error\n            or getattr(sample_result, 'status_message', None)\n            or 'no error reported')","tryCatchPattern":"try:\n    run_ace_step_generation(...)\nexcept RuntimeError as err:\n    if 'create_sample failed' in str(err):\n        # LLM metadata step failed: fall back to user-supplied caption/lyrics or re-raise\n        if caption and lyrics:\n            logging.warning('%s; continuing with user-supplied caption/lyrics', err)\n        else:\n            raise\n    else:\n        raise","preventionTips":["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"],"tags":["python-backend","ace-step","llm","music-generation"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}