CoplayDev/unity-mcp · error · ValueError

set-pixels must be a JSON object

Error message

set-pixels must be a JSON object

What it means

Thrown by _normalize_set_pixels() when, after an optional JSON-string parse, the value is not a Python dict. Because try_parse_json already converts JSON strings to objects, this fires when the parsed JSON is an array, number, string, or boolean, or when the caller passes a non-dict Python value (e.g. a list) directly. The command requires a JSON object because it reads keys like pixels, color, width, height.

Source

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

            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")
        width = int(width)
        height = int(height)
        if width <= 0 or height <= 0:
            raise ValueError("set-pixels width and height must be positive")
        result["width"] = width
        result["height"] = height
        result["pixels"] = _normalize_pixels(
            value["pixels"], width, height, "set-pixels pixels")

View on GitHub (pinned to c21bf496bc)

Solutions

1. Wrap the payload in a JSON object: `--set-pixels '{"pixels":[...],"width":2,"height":2}'`.
2. If using color fill, use `--set-pixels '{"color":"#FF0000","width":2,"height":2}'`.
3. Validate the JSON with `python -c "import json,sys; print(type(json.loads(sys.argv[1])))" '<value>'` to confirm it is a dict before running.

Example fix

// before
--set-pixels '["#FF0000","#00FF00"]'
// after
--set-pixels '{"color":"#FF0000","width":2,"height":2}'

import json
if isinstance(value, str):
    value = json.loads(value)  # will raise JSONDecodeError, distinct from this error
if not isinstance(value, dict):
    raise ValueError("set-pixels must be a JSON object")

def is_set_pixels_obj(v) -> bool:
    if isinstance(v, str):
        try:
            v = json.loads(v)
        except json.JSONDecodeError:
            return False
    return isinstance(v, dict)

try:
    payload = _normalize_set_pixels(raw)
except ValueError as e:
    # report and exit
    ...

When it happens

Trigger: Passing set-pixels as a JSON array or scalar string such as `--set-pixels '[1,2,3]'` or `--set-pixels '42'`, or calling _normalize_set_pixels with a list/number. Passing valid JSON that is not an object (e.g. a bare quoted string).

Common situations: A developer pastes a pixel array directly as set-pixels instead of wrapping it in an object (`{"pixels":[...]}`), or confuses the set-pixels object with the raw pixels list. Also happens when the JSON string is quoted so it parses to a scalar.

Related errors

• import_settings must be a JSON object
• set-pixels is required
• set-pixels requires width and height when pixels are provide
• set-pixels width and height must be positive
• set-pixels requires 'color' or 'pixels'

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