What causes "LLM returned empty script." in unclecode/crawl4ai?

Retry the compile call — empty completions from filters or sampling are frequently transient.

unclecode/crawl4ai · error · RuntimeError

LLM returned empty script.

Error message

LLM returned empty script.

What it means

RuntimeError from the c4a_compile pipeline: the configured LLM returned a response whose content, after stripping whitespace and accidental markdown code fences, is empty. The pipeline refuses to return an empty string as compiled JavaScript because downstream execution would fail confusingly.

Source

Thrown at crawl4ai/script/c4a_compile.py:380

        full_prompt =  f"{GENERATE_SCRIPT_PROMPT}\n\n{user_prompt}" if mode == "c4a" else f"{GENERATE_JS_SCRIPT_PROMPT}\n\n{user_prompt}"
        
        response = perform_completion_with_backoff(
            provider=llm_config.provider,
            prompt_with_variables=full_prompt,
            api_token=llm_config.api_token,
            json_response=False,
            base_url=getattr(llm_config, 'base_url', None),
            **completion_kwargs,
        )
        
        # Extract content from the response
        raw_response = response.choices[0].message.content.strip()

        # Strip accidental markdown fences (```js … ```)
        clean = re.sub(r"^```(?:[a-zA-Z0-9_-]+)?\s*|```$", "", raw_response, flags=re.MULTILINE).strip()

        if not clean:
            raise RuntimeError("LLM returned empty script.")

        return clean


# Convenience functions for direct use
def compile(script: Union[str, List[str]], root: Optional[pathlib.Path] = None) -> CompilationResult:
    """Compile C4A-Script to JavaScript"""
    return C4ACompiler.compile(script, root)


def validate(script: Union[str, List[str]]) -> ValidationResult:
    """Validate C4A-Script syntax"""
    return C4ACompiler.validate(script)


def compile_file(path: Union[str, pathlib.Path]) -> CompilationResult:
    """Compile C4A-Script file"""
    return C4ACompiler.compile_file(path)

View on GitHub (pinned to 7e80152142)

Solutions

Retry the compile call — empty completions from filters or sampling are frequently transient.
Inspect the raw LLM response (log response.choices[0]) to see whether content was moved to a refusal/tool-call field or filtered.
Check llm_config (model name, base_url, provider) matches an API that returns plain text content.
Simplify the input script or split it; overly long or odd prompts can push models into degenerate outputs.
As a last resort, use the deterministic (non-LLM) compiler path compile()/validate() in the same module, which never calls an LLM.

Example fix

# before
js = llm_compile(script, llm_config=cfg)  # RuntimeError: LLM returned empty script.

# after
for attempt in range(3):
    try:
        js = llm_compile(script, llm_config=cfg)
        break
    except RuntimeError as e:
        if "empty script" not in str(e) or attempt == 2:
            raise
# or avoid the LLM entirely:
js = compile(script)  # deterministic C4A compiler

Defensive patterns

Strategy: retry

Try / catch

for attempt in range(3):
    try:
        js = llm_compile(script, llm_config=cfg)
        break
    except RuntimeError as e:
        if "empty script" not in str(e) or attempt == 2:
            raise
        logger.warning(f"Empty LLM response, retry {attempt + 1}/3")

Prevention

Log response.choices[0] on failure to spot content filtering or tool-call-only replies.
Prefer the deterministic compile()/validate() path when you don't need an LLM.
Keep llm_config (model, base_url, provider) verified against a working API before batch compiles.

When it happens

Trigger: Calling the LLM-based C4A-Script compiler (compile via LLM, e.g. LLMCompiler/compile functions) where response.choices[0].message.content is '', whitespace only, or contains nothing but ``` fences. Typical with content-filtered responses, misrouted API endpoints returning empty completions, or a chat model putting output in tool calls / refusal fields instead of content.

Common situations: Content filters triggering on the script text, using a reasoning model whose visible content is empty (answer in reasoning channel), wrong base_url pointing at an incompatible API, temperature/max_tokens settings yielding empty completions, or model versions that respond with empty content on system-prompt overflow.

Related errors

AI-assisted analysis of unclecode/crawl4ai@7e80152142 (2026-08-14). Data as JSON: /api/errors/8ba6024b3d7d0422. Report an issue: GitHub.