stride3d/stride · error · YamlException

Cannot add item with key

Error message

Cannot add item with key [{keyValue.Key}] to dictionary of type [{objectContext.Descriptor}]:
{ex.Message}

What it means

DictionarySerializer wraps any exception that occurs while adding a deserialized key/value pair into the target dictionary in a YamlException pinpointing the key-value node, preserving the underlying ex.Message. It signals the pair could not be inserted into the dictionary of that type.

Solutions

Fix or remove the offending key in the YAML document at the reported location
Ensure the dictionary type's Add/AddToDictionary can accept all serialized keys (no duplicates, valid keys)
Check the inner exception (ex.Message) for the underlying cause
Enable SerializerContext.AllowErrors if partial deserialization with skipped errors is acceptable

Example fix

// before
sizes:
  small: 1
  small: 2   // duplicate key rejected by dictionary
// after
sizes:
  small: 1
  medium: 2

Defensive patterns

Strategy: try-catch

Validate before calling

// Detect duplicate keys before deserialization
var seen = new HashSet<string>();
foreach (var key in mappingKeys)
    if (!seen.Add(key)) throw new YamlException(key, $"Duplicate dictionary key '{key}'");

Try / catch

try
{
    dictSerializer.ReadYaml(ref objectContext);
}
catch (YamlException ex) when (ex.Message.StartsWith("Cannot add item with key"))
{
    logger.LogError(ex.InnerException, "Failed to add entry at {Start}", ex.Start);
}

Prevention

Ensure unique keys in YAML mappings
Avoid custom dictionary Add overrides that reject valid entries
Check the inner exception for the underlying Add failure

When it happens

Trigger: An exception thrown by dictionaryDescriptor.AddToDictionary during ReadDictionaryItems — duplicate keys when Add throws, key type conversion failure not caught earlier, or a keyed collection whose Add method rejects the entry.

Common situations: Duplicate keys in YAML mapping for dictionaries backed by keyed collections that disallow re-adding; key types with custom equality where deserialized key is invalid; custom dictionary subclasses with guarded Add.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/8677ead134e312c3. Report an issue: GitHub.

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Serialization/Serializers/DictionarySerializer.cs:163

            var reader = objectContext.Reader;
            while (!reader.Accept<MappingEnd>())
            {
                var currentDepth = objectContext.Reader.CurrentDepth;
                var startParsingEvent = objectContext.Reader.Parser.Current;

                try
                {
                    // Read key and value
                    var keyValue = ReadDictionaryItem(ref objectContext, new KeyValuePair<Type, Type>(dictionaryDescriptor.KeyType, dictionaryDescriptor.ValueType));
                    try
                    {
                        dictionaryDescriptor.AddToDictionary(objectContext.Instance, keyValue.Key, keyValue.Value);
                    }
                    catch (Exception ex)
                    {
                        ex = ex.Unwrap();
                        throw new YamlException(reader.Parser.Current.Start, reader.Parser.Current.End, $"Cannot add item with key [{keyValue.Key}] to dictionary of type [{objectContext.Descriptor}]:\n{ex.Message}", ex);
                    }
                }
                catch (YamlException ex)
                {
                    if (objectContext.SerializerContext.AllowErrors)
                    {
                        var logger = objectContext.SerializerContext.Logger;
                        logger?.Warning($"{ex.Message}, this dictionary item will be ignored", ex);
                        objectContext.Reader.Skip(currentDepth, startParsingEvent == objectContext.Reader.Parser.Current);
                    }
                    else throw;
                }
            }
        }

        /// <summary>
        /// Reads a dictionary item key-value.
        /// </summary>

View on GitHub (pinned to 96fad776d2)