BerriAI/litellm · error · ValueError

Error transforming color guided generation params

Error message

Error transforming color guided generation params: {e}. Got params: {color_guided_generation_params}, Expected params: {AmazonNovaCanvasColorGuidedGenerationParams.__annotations__}

What it means

For COLOR_GUIDED_GENERATION requests, LiteLLM builds colorGuidedGenerationParams (injecting 'text') and constructs AmazonNovaCanvasColorGuidedGenerationParams(**params); unknown keys raise TypeError, wrapped in this ValueError with the raw dict and expected annotations. Annotated keys: colors (list of hex strings), referenceImage (base64), text, negativeText.

Solutions

  1. Use annotated camelCase keys only: colors, referenceImage, text, negativeText
  2. Pass colors as a list of hex strings, e.g. colors=['#FF0000', '#00FF00']
  3. Base64-encode referenceImage; do not pass a file object or URL
  4. Check the message's 'Got params' dict to spot the exact stray key

Example fix

# before
resp = litellm.image(
    model="bedrock/amazon.nova-canvas-v1:0",
    prompt="a logo",
    taskType="COLOR_GUIDED_GENERATION",
    colors="#FF0000",                 # string, not list
    reference_image=ref_b64,          # wrong key
)

# after
resp = litellm.image(
    model="bedrock/amazon.nova-canvas-v1:0",
    prompt="a logo",
    taskType="COLOR_GUIDED_GENERATION",
    colorGuidedGenerationParams={"colors": ["#FF0000"], "referenceImage": ref_b64},
)
Defensive patterns

Strategy: validation

Validate before calling

from litellm.types.llms.bedrock import AmazonNovaCanvasColorGuidedGenerationParams

def validate_color_guided_params(p: dict) -> None:
    allowed = set(AmazonNovaCanvasColorGuidedGenerationParams.__annotations__)
    stray = set(p) - allowed
    assert not stray, f"unknown keys: {stray}; allowed: {sorted(allowed)}"
    colors = p.get("colors", [])
    assert isinstance(colors, list) and all(isinstance(c, str) and c.startswith("#") for c in colors), (
        "colors must be a list of hex strings"
    )

validate_color_guided_params(color_params)

Type guard

def is_valid_color_guided_params(p: dict) -> bool:
    """True when keys match the TypedDict and colors is a list of hex strings."""
    from litellm.types.llms.bedrock import AmazonNovaCanvasColorGuidedGenerationParams
    allowed = set(AmazonNovaCanvasColorGuidedGenerationParams.__annotations__)
    colors = p.get("colors", [])
    return (
        set(p) <= allowed
        and isinstance(colors, list)
        and all(isinstance(c, str) and c.startswith("#") for c in colors)
    )

Try / catch

try:
    resp = litellm.image(...)
except ValueError as e:
    if "Error transforming color guided generation params" in str(e):
        raise UserInputError("colors must be ['#RRGGBB', ...] with valid keys") from e
    raise

Prevention

When it happens

Trigger: Passing colors='#00AAFF' as a plain string, an unknown key like 'colorList' or 'reference_image' inside colorGuidedGenerationParams, or extra user kwargs that merged into the params dict during a litellm.image call with taskType='COLOR_GUIDED_GENERATION'.

Common situations: Translating AWS SDK color-guided examples with renamed keys; storing colors as a single string instead of a list; forwarding unvalidated user JSON as optional params.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/54a4de07352a1af2. Report an issue: GitHub.

Appendix: source

Thrown at litellm/llms/bedrock/image_generation/amazon_nova_canvas_transformation.py:110

            return AmazonNovaCanvasTextToImageRequest(
                textToImageParams=text_to_image_params_typed,
                taskType=task_type,
                imageGenerationConfig=image_generation_config_typed,
            )
        if task_type == "COLOR_GUIDED_GENERATION":
            color_guided_generation_params: dict[str, Any] = image_generation_config.pop(
                "colorGuidedGenerationParams", {}
            )
            color_guided_generation_params = {
                "text": text,
                **color_guided_generation_params,
            }
            try:
                color_guided_generation_params_typed: Final = AmazonNovaCanvasColorGuidedGenerationParams(
                    **color_guided_generation_params
                )
            except Exception as e:
                raise ValueError(
                    f"Error transforming color guided generation params: {e}. Got params: {color_guided_generation_params}, Expected params: {AmazonNovaCanvasColorGuidedGenerationParams.__annotations__}"
                )

            try:
                image_generation_config_typed = AmazonNovaCanvasImageGenerationConfig(**image_generation_config)
            except Exception as e:
                raise ValueError(
                    f"Error transforming image generation config: {e}. Got params: {image_generation_config}, Expected params: {AmazonNovaCanvasImageGenerationConfig.__annotations__}"
                )

            return AmazonNovaCanvasColorGuidedRequest(
                taskType=task_type,
                colorGuidedGenerationParams=color_guided_generation_params_typed,
                imageGenerationConfig=image_generation_config_typed,
            )
        if task_type == "INPAINTING":
            inpainting_params: dict[str, Any] = image_generation_config.pop("inpaintingParams", {})
            inpainting_params = {"text": text, **inpainting_params}

View on GitHub (pinned to 77b7c6c40c)