unslothai/unsloth · error · ValueError

prompts must be a non-empty list of non-empty strings

Error message

prompts must be a non-empty list of non-empty strings

What it means

Batch-spec validation in diffusion_batched: when a prompts list is supplied it must be non-empty and every element must be a non-empty (after strip) string. Empty lists, lists containing empty/whitespace-only strings, or lists containing non-string values (None, numbers) are rejected up front, before any generation work. The docstring contract: seed i drives prompt i when seeds are also given.

Source

Thrown at studio/backend/core/inference/diffusion_batched.py:62

    seed: Optional[int],
    seeds: Optional[list[int]],
    batch_size: int,
    draw_seed: Callable[[], int],
) -> tuple[list[tuple[str, int]], int]:
    """The per-image ``(prompt, seed)`` jobs plus the base seed for this call.

    - ``prompts`` (list): one image per prompt. With ``seeds`` too, lengths must
      match (seed i drives prompt i); without, seeds derive from the base.
    - ``seeds`` (list) alone: one image per seed, all with ``prompt``.
    - neither: ``batch_size`` images of ``prompt`` with derived seeds
      base..base+batch_size-1 (each masked JSON-safe).

    ``draw_seed`` supplies a fresh random base when the caller sent none (the
    engine passes a ``torch.Generator`` draw). Raises ``ValueError`` on empty /
    oversized lists, a length mismatch, or an out-of-range seed."""
    if prompts is not None:
        if not prompts or not all(isinstance(p, str) and p.strip() for p in prompts):
            raise ValueError("prompts must be a non-empty list of non-empty strings")
        if len(prompts) > MAX_BATCH_IMAGES:
            raise ValueError(f"prompts supports at most {MAX_BATCH_IMAGES} entries per call")
    if seeds is not None:
        if not seeds:
            raise ValueError("seeds must be a non-empty list of integers")
        if len(seeds) > MAX_BATCH_IMAGES:
            raise ValueError(f"seeds supports at most {MAX_BATCH_IMAGES} entries per call")
        seeds = [int(s) for s in seeds]
        if any(s < 0 or s > SEED_MASK for s in seeds):
            raise ValueError("every seed must be between 0 and 2**53 - 1 (JSON-safe)")
        if prompts is not None and len(seeds) != len(prompts):
            raise ValueError(
                f"prompts and seeds must have the same length "
                f"(got {len(prompts)} prompts, {len(seeds)} seeds)"
            )

    if prompts is not None:
        count = len(prompts)

View on GitHub (pinned to 203007d190)

Solutions

  1. Ensure every prompt is a non-empty trimmed string: [p for p in prompts if isinstance(p, str) and p.strip()].
  2. If the list can legitimately be empty after filtering, send prompt (singular) or omit prompts instead of an empty list.
  3. Validate client-side before the call to save a round trip.

Example fix

# before
engine.generate(prompts=["a cat", "", "a dog"])
# after
prompts = [p for p in ["a cat", "", "a dog"] if p.strip()]
engine.generate(prompts=prompts)
Defensive patterns

Strategy: validation

Validate before calling

def valid_prompts(prompts) -> bool:
    return prompts is None or (
        isinstance(prompts, list)
        and len(prompts) > 0
        and all(isinstance(p, str) and p.strip() for p in prompts)
    )

Type guard

from typing import Any

def is_valid_prompt_list(v: Any) -> bool:
    return isinstance(v, list) and bool(v) and all(isinstance(p, str) and p.strip() for p in v)

Try / catch

try:
    out = engine.generate(prompts=prompts)
except ValueError as e:
    if "prompts must be a non-empty list" in str(e):
        prompts = [p.strip() for p in prompts if isinstance(p, str) and p.strip()]
        out = engine.generate(prompts=prompts) if prompts else engine.generate(prompt=default_prompt)
    else:
        raise

Prevention

When it happens

Trigger: Calling generate with prompts=[] (empty list — note None means 'not provided' and is fine), prompts=[""], prompts=[" "], or prompts=["valid", None].

Common situations: Programmatically building prompt lists where a filter step removes every element; JSON payloads with null entries; trailing empty strings from template concatenation.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/ac3e191963b9d7fe. Report an issue: GitHub.