litedb-org/LiteDB · error · LiteException

MAPPING_ERROR

MAPPING_ERROR

Error message

Error in '{type.Name}' mapping: {ex.Message}

What it means

Thrown by BsonMapper.GetEntityMapper as LiteException(MAPPING_ERROR) wrapping any exception raised while BuildEntityMapper reflects over a type. The offending type's name and the inner exception message are embedded. The failed mapping entry is removed from the cache so a subsequent call can retry after the type is fixed.

Source

Thrown at LiteDB/Client/Mapper/BsonMapper.GetEntityMapper.cs:42

            return mapper;
        }

        using var cts = new CancellationTokenSource();
        try
        {
            // We need to add the empty shell, because ``BuildEntityMapper`` may use this method recursively
            var newMapper = new EntityMapper(type, cts.Token);
            mapper = _entities.GetOrAdd(type, newMapper);
            if (ReferenceEquals(mapper, newMapper))
            {
                try
                {
                    this.BuildEntityMapper(mapper);
                }
                catch (Exception ex)
                {
                    _entities.TryRemove(type, out _);
                    throw new LiteException(LiteException.MAPPING_ERROR, $"Error in '{type.Name}' mapping: {ex.Message}", ex);
                }
            }
        }
        finally
        {
            // Allow the Mapper to be used for de-/serialization
            cts.Cancel();
        }

        return mapper;
    }

    /// <summary>
    /// Use this method to override how your class can be, by default, mapped from entity to Bson document.
    /// Returns an EntityMapper from each requested Type
    /// </summary>
    protected void BuildEntityMapper(EntityMapper mapper)
    {

View on GitHub (pinned to f906a5f850)

Solutions

  1. Inspect the LiteException inner exception (ex.InnerException) and its message for the root cause.
  2. Fix the offending member: make it readable/settable, add a parameterless constructor, or simplify attributes.
  3. Temporarily simplify the type to a minimal class and re-add members until the culprit is isolated.

Example fix

// before
public class MyEntity
{
    public readonly int Id; // no setter, no Id detection => mapping issues
}

// after
public class MyEntity
{
    public int Id { get; set; }
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the type is mappable at startup against a known-good contract:
// - has a parameterless constructor or a [BsonCtor] constructor
// - has an Id-named property, a [BsonId] member, or an Id mapped via EntityBuilder
// - all serialized members are readable

Try / catch

try { mapper.GetEntityMapper(typeof(T)); }
catch (LiteException ex) when (ex.Code == LiteException.MAPPING_ERROR)
{
    // ex.InnerException holds the root-cause exception and message
    throw new InvalidOperationException($"Type {typeof(T)} cannot be mapped: {ex.InnerException?.Message}", ex);
}

Prevention

When it happens

Trigger: Calling any operation that triggers first-time mapping of a type (Insert, Query, ToDocument) where the type has an unreflectable member, a custom ResolveMember callback that throws, an invalid attribute combination, or a member whose type cannot itself be mapped recursively.

Common situations: A POCO with a property whose getter throws, a struct/value type with no settable fields when IncludeFields is off, a recursive DbRef cycle, or a ResolveMember hook that throws on an unexpected member.

Related errors

AI-assisted analysis of litedb-org/LiteDB@f906a5f850 (2026-08-13). Data as JSON: /api/errors/3c514e9860443380. Report an issue: GitHub.