CoplayDev/unity-mcp · error · ValueError

{context} must be a list or base64 string

Error message

{context} must be a list or base64 string

What it means

Raised by _normalize_pixels (texture.py:173) when the pixels value is not None, not a string (base64 or JSON array), and not a list — i.e. an unsupported type such as an int, float, bool, or dict. The 'context' label is 'set-pixels pixels'. After a non-base64 string is JSON-parsed it may become such a scalar/object, hitting the final fallback.

Source

Thrown at Server/src/cli/commands/texture.py:173

def _normalize_pixels(value: Any, width: int, height: int, context: str) -> list[list[int]] | str:
    if value is None:
        raise ValueError(f"{context} is required")
    if isinstance(value, str):
        if value.startswith("base64:"):
            return value
        trimmed = value.strip()
        if trimmed.startswith("[") and trimmed.endswith("]"):
            value = try_parse_json(trimmed, context)
        else:
            return f"base64:{value}"
    if isinstance(value, list):
        expected_count = width * height
        if len(value) != expected_count:
            raise ValueError(
                f"{context} must have {expected_count} entries, got {len(value)}")
        return [_normalize_color(pixel, f"{context} pixel") for pixel in value]
    raise ValueError(f"{context} must be a list or base64 string")


def _normalize_set_pixels(value: Any) -> dict[str, Any]:
    if value is None:
        raise ValueError("set-pixels is required")
    if isinstance(value, str):
        value = try_parse_json(value, "set-pixels")
    if not isinstance(value, dict):
        raise ValueError("set-pixels must be a JSON object")

    result: dict[str, Any] = dict(value)

    if "pixels" in value:
        width = value.get("width")
        height = value.get("height")
        if width is None or height is None:
            raise ValueError(
                "set-pixels requires width and height when pixels are provided")

View on GitHub (pinned to c21bf496bc)

Solutions

1. Provide pixels as a JSON array of width*height colors, or as a base64 string (optionally prefixed with 'base64:').
2. If you intended a solid fill, drop 'pixels' and use 'color' instead.
3. Ensure the pixels JSON parses to a list or stays a base64 string.

Example fix

# before
unity-mcp texture modify Assets/Tex.png --set-pixels '{"x":0,"y":0,"width":1,"height":1,"pixels":128}'

# after
unity-mcp texture modify Assets/Tex.png --set-pixels '{"x":0,"y":0,"width":1,"height":1,"pixels":[[128,128,128,255]]}'

# Python - accept only list or string for pixels before _normalize_pixels
if not isinstance(pixels, (list, str)):
    raise ValueError(f"{context} must be a list or base64 string")

def is_pixels_shape(v) -> bool: return isinstance(v, (list, str))

try:
    result = _normalize_set_pixels(set_pixels)
except ValueError as e:
    print_error(str(e)); sys.exit(1)

When it happens

Trigger: Passing `--set-pixels '{"width":2,"height":2,"pixels":128}'` (a scalar), or a pixels value of {"a":1} (a dict), or a bare number where the pixel array or base64 string was expected.

Common situations: Passing a single grayscale int for pixels; a JSON object where an array was intended; mis-typing the pixels field as a scalar.

Related errors

• {context} must be a list or hex string
• {context} must have {expected_count} entries, got {len(value
• width and height must be positive
• Invalid hex color: {value}
• {context} is required

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/1ac16c0701b8cd30. Report an issue: GitHub.