Comfy-Org/ComfyUI · error · ValueError

At least one of 'prompt' or 'reference_image' must be provid

Error message

At least one of 'prompt' or 'reference_image' must be provided.

What it means

The Beeble switchX API requires at least one content input: a text prompt or a reference image. The node strips the prompt and raises this ValueError only when the cleaned prompt is empty AND reference_image is None, so whitespace-only prompts also trigger it.

Source

Thrown at comfy_api_nodes/nodes_beeble.py:36

    downscale_video_to_max_pixels,
    poll_op,
    sync_op,
    upload_image_to_comfyapi,
    upload_video_to_comfyapi,
    validate_string,
    validate_video_frame_count,
)

_MAX_PIXELS = 2_770_000
_MAX_FRAMES = 240
_MAX_PROMPT_LEN = 2000


def _validate_inputs(prompt: str | None, reference_image: Input.Image | None) -> str | None:
    """Beeble requires at least one of prompt or reference_image. Returns the cleaned prompt."""
    cleaned = prompt.strip() if prompt else ""
    if not cleaned and reference_image is None:
        raise ValueError("At least one of 'prompt' or 'reference_image' must be provided.")
    if cleaned:
        validate_string(cleaned, strip_whitespace=False, max_length=_MAX_PROMPT_LEN)
    return cleaned or None


async def _upload_mask_as_image(
    cls: type[IO.ComfyNode],
    mask: Input.Image,
    *,
    wait_label: str,
) -> str:
    """Encode a single-frame MASK (H, W) or (1, H, W) as a PNG and upload."""
    if mask.dim() == 2:
        mask = mask.unsqueeze(0)
    image = convert_mask_to_image(mask[:1])
    return await upload_image_to_comfyapi(
        cls,
        image,

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Provide a non-empty prompt (after stripping) or connect a reference_image.
2. If the prompt comes from an upstream node, add a default/fallback so it is never blank.
3. Trim accidental whitespace-only strings before wiring them in.

Example fix

# before
beeble_node(prompt="   ", reference_image=None)  # ValueError

# after
beeble_node(prompt=prompt.strip() or "enhance this photo", reference_image=ref_img)

cleaned = (prompt or "").strip()
if not cleaned and reference_image is None:
    raise ValueError("provide prompt or reference_image")  # fail early, before node

def beeble_inputs_valid(prompt: str | None, ref) -> bool:
    return bool((prompt or "").strip()) or ref is not None

try:
    out = await beeble_node(prompt=prompt, reference_image=ref)
except ValueError as e:
    if "must be provided" in str(e):
        out = await beeble_node(prompt=default_prompt, reference_image=ref)

When it happens

Trigger: Invoking the Beeble node with prompt unset, empty, or whitespace-only while reference_image is not connected.

Common situations: Empty-string widget defaults flowing from templates; conditional workflows where the prompt upstream node produced ''; UI sending an unedited blank prompt field.

Related errors

• Custom alpha video frame count ({mask.shape[0]}) does not ma
• Unsupported process_res_method: {method}
• At least 4 points are required to compute a homography.
• Unknown reference view selection strategy: {strategy!r}. Mus
• Input img and txt tensors must have 3 dimensions.

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/6d078e1bb2fb9075. Report an issue: GitHub.