sgl-project/sglang · error · ValueError

Image is fully transparent

Error message

Image is fully transparent

What it means

Raised by recenter_image in mesh3d_utils.py when, after converting an image to RGBA and inspecting its alpha channel, every pixel has alpha == 0 — i.e. the image contains no visible content. The function crops to the alpha bounding box, so an empty mask leaves it nothing to operate on.

Source

Thrown at python/sglang/multimodal_gen/runtime/utils/mesh3d_utils.py:920

    image_pts = repeat(image_pt, "c h w -> b c h w", b=1)
    return image_pts


def recenter_image(image, border_ratio=0.2):
    """Recenter a PIL image, cropping to non-transparent content with a border."""
    from PIL import Image as PILImage

    if image.mode == "RGB":
        return image
    elif image.mode == "L":
        return image.convert("RGB")
    if image.mode != "RGBA":
        image = image.convert("RGBA")

    alpha_channel = np.array(image)[:, :, 3]
    non_zero_indices = np.argwhere(alpha_channel > 0)
    if non_zero_indices.size == 0:
        raise ValueError("Image is fully transparent")

    min_row, min_col = non_zero_indices.min(axis=0)
    max_row, max_col = non_zero_indices.max(axis=0)

    cropped_image = image.crop((min_col, min_row, max_col + 1, max_row + 1))

    width, height = cropped_image.size
    border_width = int(width * border_ratio)
    border_height = int(height * border_ratio)

    new_width = width + 2 * border_width
    new_height = height + 2 * border_height
    square_size = max(new_width, new_height)

    new_image = PILImage.new("RGBA", (square_size, square_size), (255, 255, 255, 0))

    paste_x = (square_size - new_width) // 2 + border_width
    paste_y = (square_size - new_height) // 2 + border_height

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect the input image's alpha channel (np.array(img)[:,:,3].any()) before calling recenter_image
2. Check the upstream producer of the image (mask/matting model) — an all-transparent output usually means the source step failed, not this API
3. If the image is meant to be opaque, convert with a white background instead of straight convert('RGBA') (paste onto opaque canvas)
4. If transparency is expected, validate the file renders correctly in an image viewer; re-export it

Example fix

// before
img = Image.open(path)
recenter_image(img)

// after
img = Image.open(path).convert("RGBA")
if not (np.array(img)[:, :, 3] > 0).any():
    raise ValueError(f"{path} is fully transparent; regenerate it")
recenter_image(img)

import numpy as np
from PIL import Image

def has_visible_content(img: Image.Image) -> bool:
    rgba = img.convert("RGBA")
    return bool((np.array(rgba)[:, :, 3] > 0).any())

img = Image.open(path)
if not has_visible_content(img):
    raise ValueError(f"{path} is fully transparent")

try:
    recenter_image(img)
except ValueError as e:
    if "fully transparent" in str(e):
        # regenerate the source image / re-run matting upstream
        raise

When it happens

Trigger: Calling _load_input_image / recenter_image on an RGBA (or transparent-converted) image whose alpha channel is entirely zero; e.g. an SVG/PNG render that came out fully transparent, or a mask generation step upstream produced an all-empty mask.

Common situations: Broken transparent PNG exports from design tools; upstream alpha/matte generation failing (e.g. rembg returning an empty result); images whose content lives in RGB but alpha got zeroed by a prior compositing step; corrupted image downloads.

Related errors

• input image is empty
• v_cache must be provided
• q can only be None when only_qv=True
• q must be provided unless qv is provided with only_qv=True
• `dt_bias` must have {HV * K} elements (got {dt_bias.numel()}

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/d2c469247f5e37b1. Report an issue: GitHub.