microsoft/garnet · error · RedisSerializationException

Unable to deserialize RedisOptions object. Unable to convert

Error message

Unable to deserialize RedisOptions object. Unable to convert object of type {typeof(string)} to object of type {elemType}. (Line: {lineCount}; Key: {key}; Property: {prop.Name}).

What it means

Thrown by RedisConfigSerializer.Deserialize when an array-typed option's individual element cannot be converted from string to the array's element type. The parser splits the value by spaces and attempts element-wise conversion; if any element fails TryChangeType, this error fires. The message includes line number, key, and property name for diagnosis.

Source

Thrown at libs/host/Configuration/Redis/RedisConfigSerializer.cs:111

                // Try to deserialize the value
                if (!TryChangeType(value, typeof(string), optType, out var newVal))
                {
                    // If unsuccessful and if underlying option type is an array, try to deserialize array by elements
                    if (optType.IsArray)
                    {
                        // Split the values in the serialized array
                        var values = value.Split(' ');

                        // Instantiate a new array
                        var elemType = optType.GetElementType();
                        newVal = Array.CreateInstance(elemType, values.Length);

                        // Try deserializing and setting array elements
                        for (var i = 0; i < values.Length; i++)
                        {
                            if (!TryChangeType(values[i], typeof(string), elemType, out var elem))
                                throw new RedisSerializationException(
                                    $"Unable to deserialize {nameof(RedisOptions)} object. Unable to convert object of type {typeof(string)} to object of type {elemType}. (Line: {lineCount}; Key: {key}; Property: {prop.Name}).");


                            ((Array)newVal).SetValue(elem, i);
                        }
                    }
                    else
                    {
                        throw new RedisSerializationException(
                            $"Unable to deserialize {nameof(RedisOptions)} object. Unable to convert object of type {typeof(string)} to object of type {optType}. (Line: {lineCount}; Key: {key}; Property: {prop.Name}).");
                    }
                }

                // Create a new Option<T> object
                var newOpt = Activator.CreateInstance(prop.PropertyType);

                // Set the underlying option value
                var valueProp = prop.PropertyType.GetProperty(nameof(Option<object>.Value));

View on GitHub (pinned to 951b0fc683)

Solutions

  1. Check the specific token that failed using the line number and key in the error message.
  2. Correct the malformed array element to match the expected element type.
  3. Ensure all space-separated values in the directive are valid for the property's array element type.

Example fix

// before:
//   bind 127.0.0.1 notanip

// after:
//   bind 127.0.0.1 10.0.0.1
Defensive patterns

Strategy: validation

Validate before calling

// Validate array element values before deserialization by checking the property's expected element type
var propType = typeof(RedisOptions).GetProperty(key)?.PropertyType;
if (propType != null && propType.IsArray)
{
    var elemType = propType.GetElementType();
    var converter = TypeDescriptor.GetConverter(elemType);
    foreach (var token in value.Split(' '))
        if (!converter.IsValid(token))
            throw new FormatException($"Value '{token}' is not valid for type {elemType.Name}");
}

Type guard

static bool CanConvertArrayElements(string value, Type elemType)
{
    var converter = TypeDescriptor.GetConverter(elemType);
    return value.Split(' ').All(t => converter.IsValid(t));
}

Try / catch

try
{
    var redisOpts = RedisConfigSerializer.Deserialize(reader, logger);
}
catch (RedisSerializationException ex) when (ex.Message.Contains("Unable to convert object of type"))
{
    logger.LogError("Redis config type conversion failed: {msg}", ex.Message);
    throw;
}

Prevention

When it happens

Trigger: A config line whose value is space-separated tokens intended for an array property, where at least one token cannot convert to the element type. For example, a bind directive with a non-IP value, or a port-array directive with non-numeric tokens.

Common situations: Config files with typos in array values (e.g., 'bind 127.0.0.1 abc' where 'abc' isn't a valid IP); locale differences causing decimal separator issues; copying values from a source that used a different delimiter.

Related errors

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/8627a2597d53a361. Report an issue: GitHub.