What causes "Failed to parse 'properties' JSON string. Raw value: {token}" in CoplayDev/unity-mcp?

Pass properties as a native JSON object instead of a string so the framework handles serialization.

CoplayDev/unity-mcp · error · JsonException

Failed to parse 'properties' JSON string. Raw value: {token}

Error message

Failed to parse 'properties' JSON string. Raw value: {token}

What it means

Thrown by the VFX properties parser in ManageVFX when the 'properties' parameter is a JSON string that fails to parse. The method accepts properties as a JSON object or as a string containing valid JSON; if the string is malformed, JToken.Parse raises a JsonException that is wrapped with this message including the raw value.

Source

Thrown at MCPForUnity/Editor/Tools/Vfx/ManageVFX.cs:190

            if (token == null || token.Type == JTokenType.Null)
            {
                return null;
            }

            if (token is JObject obj)
            {
                return obj;
            }

            if (token.Type == JTokenType.String)
            {
                try
                {
                    return JToken.Parse(token.ToString()) as JObject;
                }
                catch (JsonException ex)
                {
                    throw new JsonException(  
                        $"Failed to parse 'properties' JSON string. Raw value: {token}",  
                        ex); 
                }
            }

            return null;
        }

        private static string NormalizeKey(string key, bool allowAliases)
        {
            if (string.IsNullOrEmpty(key))
            {
                return key;
            }
            if (string.Equals(key, "action", StringComparison.OrdinalIgnoreCase))
            {
                return "action";
            }

View on GitHub (pinned to c21bf496bc)

Solutions

Pass properties as a native JSON object instead of a string so the framework handles serialization.
Validate the JSON string locally with a parser before sending (e.g. json.loads in Python).
Use double quotes for all JSON keys and string values.
If building the string programmatically, use json.dumps() rather than string formatting.

Example fix

// before (malformed JSON string)
params = {"properties": "{emissionRate: 100,}"}
// after (native object)
params = {"properties": {"emissionRate": 100}}

Defensive patterns

Strategy: validation

Validate before calling

import json

def validate_properties_json(props):
    if isinstance(props, dict):
        return True
    if isinstance(props, str):
        try:
            json.loads(props)
            return True
        except json.JSONDecodeError:
            return False
    return False

Try / catch

try
{
    var propsObj = ParsePropertiesToken(token);
}
catch (JsonException ex) when (ex.Message.Contains("Failed to parse 'properties'"))
{
    return new ErrorResponse($"Invalid properties JSON: {ex.Message}");
}

Prevention

Pass properties as a native JSON object rather than a string to let the framework serialize.
Always validate JSON strings with a parser before sending.
Use json.dumps() for serialization, never string formatting.
Ensure double quotes throughout JSON.

When it happens

Trigger: Calling a VFX tool (set_property, configure, etc.) with properties passed as a JSON string that contains a syntax error: missing quotes, trailing commas, unescaped characters, or truncated JSON.

Common situations: AI generates JSON by string concatenation instead of using a serializer; copy-paste introduces invisible characters or truncation; properties string is actually a key=value format rather than JSON; single quotes used instead of double quotes.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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