sgl-project/sglang · error · ValueError

height/width must be between 256 and 2048

Error message

height/width must be between 256 and 2048

What it means

The Ideogram stage validates requested image dimensions before building model inputs. Height and width must each lie in [256, 2048] pixels; anything outside that range is rejected because the model was trained only within that resolution range.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/ideogram.py:147

        )
        encoded = self.tokenizers[0](
            text, return_tensors="pt", add_special_tokens=False
        )
        token_ids = encoded["input_ids"][0]
        num_text_tokens = int(token_ids.shape[0])
        if num_text_tokens > max_text_tokens:
            raise ValueError(
                f"prompt has {num_text_tokens} tokens, exceeds max_text_tokens={max_text_tokens}"
            )
        return token_ids, num_text_tokens

    def _build_inputs(self, prompts: list[str], height: int, width: int, server_args):
        cfg = server_args.pipeline_config
        tokenized = [self._tokenize(p, cfg.max_text_tokens) for p in prompts]
        batch_size = len(prompts)
        patch = cfg.patch_size * cfg.ae_scale_factor
        if height < 256 or height > 2048 or width < 256 or width > 2048:
            raise ValueError("height/width must be between 256 and 2048")
        if height % patch != 0 or width % patch != 0:
            raise ValueError(
                f"height/width must be divisible by patch_size*ae_scale_factor={patch}"
            )
        grid_h = height // patch
        grid_w = width // patch
        num_image_tokens = grid_h * grid_w
        max_text_tokens = max(num_text for _, num_text in tokenized)
        total_seq_len = max_text_tokens + num_image_tokens
        device = get_local_torch_device()

        h_idx = torch.arange(grid_h).view(-1, 1).expand(grid_h, grid_w).reshape(-1)
        w_idx = torch.arange(grid_w).view(1, -1).expand(grid_h, grid_w).reshape(-1)
        t_idx = torch.zeros_like(h_idx)
        image_pos = torch.stack([t_idx, h_idx, w_idx], dim=1) + IMAGE_POSITION_OFFSET

        token_ids = torch.zeros(batch_size, total_seq_len, dtype=torch.long)
        text_position_ids = torch.zeros(batch_size, total_seq_len, 3, dtype=torch.long)

View on GitHub (pinned to 0132848349)

Solutions

1. Clamp height and width to [256, 2048]
2. Round the request to the nearest valid resolution (also respecting the patch divisibility rule)

Example fix

# before
img = stage(prompts=[p], height=240, width=1024)
# after
height = min(max(height, 256), 2048)
width = min(max(width, 256), 2048)
img = stage(prompts=[p], height=height, width=width)

if not (256 <= height <= 2048 and 256 <= width <= 2048):
    height = min(max(height, 256), 2048)
    width = min(max(width, 256), 2048)

When it happens

Trigger: Calling forward/generate with height or width below 256 or above 2048 (e.g. 128x128 thumbnails or 4096-wide panoramas).

Common situations: Defaulting to a square 1024 but allowing user-supplied sizes; UI sliders permitting out-of-range values; copying dimensions from another model (e.g. SDXL's 2048+) without clamping.

Related errors

• height/width must be divisible by patch_size*ae_scale_factor
• condition_frame_indexes={cond_indexes} exceeds the latent fr
• prompt has {num_text_tokens} tokens, exceeds max_text_tokens
• Unknown Ideogram 4 preset {preset!r}; expected one of {sorte
• v_cache must be provided

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