{"record":{"id":"03d609eefd9bb874","repo":"invoke-ai/InvokeAI","slug":"reference-image-dimensions-must-be-multiples-of-8","errorCode":null,"errorMessage":"Reference-image dimensions must be multiples of 8 (got {width}x{height}).","messagePattern":"Reference-image dimensions must be multiples of 8 \\(got (.+?)x(.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/wan/extensions/wan_ref_image_extension.py","lineNumber":31,"sourceCode":"with ``num_frames=1`` and ``expand_timesteps=False`` (the defaults for\nsingle-frame image generation).\n\"\"\"\n\nimport torch\nimport torchvision.transforms.functional as TF\nfrom diffusers.models.autoencoders import AutoencoderKLWan\nfrom PIL import Image\n\n# Wan 2.2 VAE temporal scale factor — single frame still consumes a 4-position\n# slice of the mask tensor, which is why the mask contributes 4 channels.\n_WAN_VAE_TEMPORAL_SCALE = 4\n\n\ndef preprocess_reference_image(image: Image.Image, width: int, height: int) -> torch.Tensor:\n    \"\"\"Resize a PIL image to (width, height) and return a normalised [-1, 1]\n    tensor of shape ``[1, 3, 1, height, width]`` ready for ``AutoencoderKLWan.encode``.\"\"\"\n    if width % 8 != 0 or height % 8 != 0:\n        raise ValueError(f\"Reference-image dimensions must be multiples of 8 (got {width}x{height}).\")\n    resized = image.convert(\"RGB\").resize((width, height), Image.LANCZOS)\n    # [0, 1] CHW float tensor.\n    pixel = TF.to_tensor(resized)\n    # Scale to [-1, 1] to match the Wan VAE's expected input range.\n    pixel = pixel * 2.0 - 1.0\n    # [3, H, W] -> [1, 3, 1, H, W]: add batch + temporal dims.\n    return pixel.unsqueeze(0).unsqueeze(2)\n\n\ndef encode_reference_image_to_ti2v_condition(\n    image: Image.Image,\n    vae: AutoencoderKLWan,\n    width: int,\n    height: int,\n    device: torch.device,\n    dtype: torch.dtype,\n) -> torch.Tensor:\n    \"\"\"Build the TI2V-5B-style reference condition tensor.","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/wan/extensions/wan_ref_image_extension.py#L13-L49","documentation":"preprocess_reference_image resizes a PIL image to (width, height) for the Wan VAE, which requires spatial dims aligned to the model's 8x downsampling factor. If either dimension is not a multiple of 8, the library raises this ValueError before touching the VAE, preventing silent latent misalignment or decoder crashes.","triggerScenarios":"Calling preprocess_reference_image directly, or indirectly via encode_reference_image_to_ti2v_condition / encode_reference_image_to_condition / encode_reference_image_to_video_condition, with width or height such that width % 8 != 0 or height % 8 != 0 (e.g. 517x369).","commonSituations":"Deriving dimensions from the source image's native size, rounding a computed aspect-preserving size with int() instead of rounding down to a multiple of 8, hand-entering resolutions from other models with different patch factors.","solutions":["Round both dims down to the nearest multiple of 8: width = (width // 8) * 8; height = (height // 8) * 8.","Use a standard Wan resolution that is a multiple of 8 (e.g. 1280x720, 832x480).","If dimensions come from user input or config, validate/normalize them before calling the extension."],"exampleFix":"// before\nw, h = image.size  # e.g. 1023x681\npixel = preprocess_reference_image(image, w, h)\n// after\nw = (image.size[0] // 8) * 8\nh = (image.size[1] // 8) * 8\npixel = preprocess_reference_image(image, w, h)","handlingStrategy":"validation","validationCode":"width = (width // 8) * 8\nheight = (height // 8) * 8\nassert width % 8 == 0 and height % 8 == 0 and width > 0 and height > 0\npixel = preprocess_reference_image(image, width, height)","typeGuard":null,"tryCatchPattern":"try:\n    pixel = preprocess_reference_image(image, w, h)\nexcept ValueError as e:\n    if \"multiples of 8\" in str(e):\n        pixel = preprocess_reference_image(image, (w // 8) * 8, (h // 8) * 8)","preventionTips":["Round requested dimensions down to the nearest multiple of 8.","Prefer known-good Wan resolutions (e.g. 1280x720, 832x480).","Validate user/config-supplied dimensions before image preprocessing."],"tags":["python","pytorch","image-processing","dimensions","wan"],"backgroundTag":"dimension-not-multiple-of-stride","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}