invoke-ai/InvokeAI · error · ValueError

Unsupported reference_illuminant: {reference_illuminant}

Error message

Unsupported reference_illuminant: {reference_illuminant}

What it means

_require_reference_illuminant validates the white-point identifier (e.g. 'D65') against the known _REFERENCE_ILLUMINANTS set and normalizes it to uppercase; unknown names cannot be mapped to a chromaticity.

Source

Thrown at invokeai/backend/image_util/color_conversion.py:63

    (1.0, -0.0894841775, -1.2914855480),
)
_LMS_TO_LINEAR_SRGB_MATRIX = (
    (4.0767416621, -3.3077115913, 0.2309699292),
    (-1.2684380046, 2.6097574011, -0.3413193965),
    (-0.0041960863, -0.7034186147, 1.7076147010),
)


def _require_color_tensor(color_tensor: torch.Tensor) -> torch.Tensor:
    if color_tensor.ndim != 3 or color_tensor.shape[0] != 3:
        raise ValueError("color_tensor must be a 3xHxW tensor")
    return color_tensor


def _require_reference_illuminant(reference_illuminant: str) -> str:
    normalized = reference_illuminant.upper()
    if normalized not in _REFERENCE_ILLUMINANTS:
        raise ValueError(f"Unsupported reference_illuminant: {reference_illuminant}")
    return normalized


def _full_like_spatial(reference_tensor: torch.Tensor, fill_value: float) -> torch.Tensor:
    return torch.full(
        reference_tensor.shape[1:], fill_value, dtype=reference_tensor.dtype, device=reference_tensor.device
    )


def _degrees_from_unit_hue(unit_hue_tensor: torch.Tensor) -> torch.Tensor:
    return torch.remainder(unit_hue_tensor * 360.0, 360.0)


def _unit_hue_from_degrees(hue_tensor: torch.Tensor) -> torch.Tensor:
    return torch.remainder(hue_tensor, 360.0) / 360.0


def _matrix_tensor(matrix: tuple[tuple[float, ...], ...], reference_tensor: torch.Tensor) -> torch.Tensor:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Use a supported illuminant name such as 'D65' (check _REFERENCE_ILLUMINANTS for the exact set)
2. Pass the name in any case — it is uppercased internally — but fix spelling/whitespace
3. Pick the closest supported illuminant and adapt your data accordingly

Example fix

// before
xyz_from_lab(lab, reference_illuminant="d60")
// after
xyz_from_lab(lab, reference_illuminant="D65")

from invokeai.backend.image_util.color_conversion import _REFERENCE_ILLUMINANTS
if illuminant.upper() not in _REFERENCE_ILLUMINANTS:
    illuminant = "D65"  # safe default

def is_supported_illuminant(name: str, valid=frozenset({'D65','D50'})) -> bool:
    return name.upper() in valid

try:
    xyz = xyz_from_lab(lab, reference_illuminant=illuminant)
except ValueError as e:
    if "Unsupported reference_illuminant" in str(e):
        xyz = xyz_from_lab(lab, reference_illuminant="D65")
    else:
        raise

When it happens

Trigger: Calling lab_from_xyz, xyz_from_lab, or _adapt_xyz-dependent helpers with reference_illuminant like 'd65 ' (unnormalized usage), 'D50 ' typo, or a name not in the supported set.

Common situations: Copy-pasting illuminant names from other libraries with different spellings (e.g. 'D65/2°'), lowercase/whitespace variants when calling outside the guard, assuming arbitrary illuminants are supported.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported noise type: {noise_type}
• color_tensor must be a 3xHxW tensor
• No external provider config fields provided
• str(e)
• str(e) (ValueError from user service update, e.g. LastAdmini

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/bb7ad4f428028323. Report an issue: GitHub.