{"record":{"id":"6c289ca75d1b177e","repo":"FasterXML/jackson-databind","slug":"cannot-deserialize-singleton-container-from-size","errorCode":null,"errorMessage":"Cannot deserialize Singleton container from ${size} entries","messagePattern":"Cannot deserialize Singleton container from (.+?) entries","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/tools/jackson/databind/deser/jdk/JavaUtilCollectionsDeserializers.java","lineNumber":266,"sourceCode":"                return value;\n            }\n        }\n\n        @Override\n        public JavaType getInputType(TypeFactory typeFactory) {\n            return _inputType;\n        }\n\n        @Override\n        public JavaType getOutputType(TypeFactory typeFactory) {\n            // we don't actually care, so:\n            return _inputType;\n        }\n\n        private void _checkSingleton(int size) {\n            if (size != 1) {\n                // not the best error ever but... has to do\n                throw new IllegalArgumentException(\"Cannot deserialize Singleton container from \"+size+\" entries\");\n            }\n        }\n    }\n}\n","sourceCodeStart":248,"sourceCodeEnd":271,"githubUrl":"https://github.com/FasterXML/jackson-databind/blob/a50c7d2a1d57234ac4adf70dbd88ac90db6436e4/src/main/java/tools/jackson/databind/deser/jdk/JavaUtilCollectionsDeserializers.java#L248-L271","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the JSON provides exactly one element for fields typed as singleton containers.","Change the target field type to a regular List, Set, or Map instead of a singleton container type.","If the data legitimately has 0 or 2+ elements, use List<T> or Set<T> not Collections.singleton*.","Add a custom deserializer if you need to handle variable-size input for these special types."],"exampleFix":"// before: field typed as singleton list but JSON has 2 items\n// JSON: [\"a\",\"b\"]\nCollections.singletonList(\"a\") result;\n// after: use regular List\nList<String> result = Arrays.asList(\"a\",\"b\");","handlingStrategy":"validation","validationCode":"// Validate JSON element count before deserializing into singleton types\nJsonNode node = mapper.readTree(json);\nint size = node.isArray() ? node.size() : node.size();\nif (size != 1) {\n    throw new IllegalArgumentException(\"Expected 1 entry for singleton, got \" + size);\n}","typeGuard":null,"tryCatchPattern":"try {\n    mapper.readValue(json, singletonListType);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Singleton container\")) {\n        // JSON has wrong number of elements — fix data or change target type\n    }\n}","preventionTips":["Do not use Collections.singleton* result types as deserialization targets.","Use List<T>, Set<T>, or Map<K,V> for variable-size data.","Validate cardinality before deserializing into constrained container types."],"tags":["jackson","deserialization","singleton","collections","cardinality"],"analyzedSha":"a50c7d2a1d57234ac4adf70dbd88ac90db6436e4","analyzedAt":"2026-08-06T20:31:51.404Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}