unslothai/unsloth · error · ValueError

prompts supports at most {MAX_BATCH_IMAGES} entries per call

Error message

prompts supports at most {MAX_BATCH_IMAGES} entries per call

What it means

The prompts list is capped at MAX_BATCH_IMAGES = 32 entries per call. This bounds VRAM and time for one request; anything longer is a ValueError before generation starts. Send multiple calls if you need more images.

Source

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

    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)
    elif seeds is not None:
        count = len(seeds)

View on GitHub (pinned to 203007d190)

Solutions

  1. Chunk the list client-side into batches of at most 32 and issue one call per chunk.
  2. Alternatively use the seeds list form (also capped at 32) or repeated single-prompt calls.

Example fix

# before
engine.generate(prompts=all_100_prompts)
# after
MAX = 32
for i in range(0, len(all_100_prompts), MAX):
    engine.generate(prompts=all_100_prompts[i:i+MAX])
Defensive patterns

Strategy: validation

Validate before calling

MAX_BATCH_IMAGES = 32

def chunked(seq, n=MAX_BATCH_IMAGES):
    for i in range(0, len(seq), n):
        yield seq[i:i+n]

Type guard

def within_batch_limit(prompts) -> bool:
    return prompts is None or len(prompts) <= 32

Try / catch

try:
    out = engine.generate(prompts=prompts)
except ValueError as e:
    if "at most" in str(e) and "prompts" in str(e):
        out = [engine.generate(prompts=c) for c in chunked(prompts)]
    else:
        raise

Prevention

When it happens

Trigger: Calling generate with a prompts list of 33+ entries (len(prompts) > 32).

Common situations: Bulk generation scripts feeding a whole CSV of prompts in one request; prompt-enumeration loops (styles x subjects) exceeding 32 combinations.

Related errors

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