FasterXML/jackson-databind · error · IllegalArgumentException

Cannot deserialize Singleton container from ${size} entries

Error message

Cannot deserialize Singleton container from ${size} entries

What it means

Thrown by JavaUtilCollectionsConverter._checkSingleton when deserializing into a singleton container type (Collections.singleton, Collections.singletonList, Collections.singletonMap — the TYPE_SINGLETON_SET/LIST/MAP variants) and the deserialized value has a size other than 1. Singleton containers by definition hold exactly one element; receiving zero or multiple elements is a type-level constraint violation.

Source

Thrown at src/main/java/tools/jackson/databind/deser/jdk/JavaUtilCollectionsDeserializers.java:266

                return value;
            }
        }

        @Override
        public JavaType getInputType(TypeFactory typeFactory) {
            return _inputType;
        }

        @Override
        public JavaType getOutputType(TypeFactory typeFactory) {
            // we don't actually care, so:
            return _inputType;
        }

        private void _checkSingleton(int size) {
            if (size != 1) {
                // not the best error ever but... has to do
                throw new IllegalArgumentException("Cannot deserialize Singleton container from "+size+" entries");
            }
        }
    }
}

View on GitHub (pinned to a50c7d2a1d)

Solutions

1. Ensure the JSON provides exactly one element for fields typed as singleton containers.
2. Change the target field type to a regular List, Set, or Map instead of a singleton container type.
3. If the data legitimately has 0 or 2+ elements, use List<T> or Set<T> not Collections.singleton*.
4. Add a custom deserializer if you need to handle variable-size input for these special types.

Example fix

// before: field typed as singleton list but JSON has 2 items
// JSON: ["a","b"]
Collections.singletonList("a") result;
// after: use regular List
List<String> result = Arrays.asList("a","b");

// Validate JSON element count before deserializing into singleton types
JsonNode node = mapper.readTree(json);
int size = node.isArray() ? node.size() : node.size();
if (size != 1) {
    throw new IllegalArgumentException("Expected 1 entry for singleton, got " + size);
}

try {
    mapper.readValue(json, singletonListType);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Singleton container")) {
        // JSON has wrong number of elements — fix data or change target type
    }
}

When it happens

Trigger: Deserializing JSON into a field typed as the result of Collections.singleton/singletonList/singletonMap where the JSON provides 0 or 2+ elements. Using Jackson's type handling to reconstruct a singleton container from a JSON array or object with the wrong cardinality.

Common situations: A field that was serialized from a singleton collection but the JSON was subsequently modified to add/remove elements. Round-tripping data through a type that happens to be a Collections$SingletonList/Set/Map. Using Java's immutable collection factory List.of(x) / Set.of(x) which Jackson maps to singleton or immutable variants.

Related errors

• Trying to resolve a forward reference with id [{}] that wasn
• Cannot call withValueDeserializer() on {}
• Cannot pass null property name
• Duplicate creator property "%s" (index %s vs %d) for type %s
• Conflicting %s creators: already had %s creator %s, encounte

AI-assisted analysis of FasterXML/jackson-databind@a50c7d2a1d (2026-08-06). Data as JSON: /api/errors/6c289ca75d1b177e. Report an issue: GitHub.